.svg?format=pjpg&auto=webp)
.svg?format=pjpg&auto=webp)
.svg?format=pjpg&auto=webp)
.svg?format=pjpg&auto=webp)
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
Contentstack offers the TypeScript Delivery SDK for building applications. Below, is an in-depth guide and valuable resources to initiate your journey with our TypeScript Delivery SDK. Additionally, the SDK supports the creating applications for Node.js and React Native environments.
Additional Resource: To know more about the TypeScript Delivery SDK, refer to the About TypeScript Delivery SDK and Get Started with TypeScript Delivery SDK documentation.
The Contentstack module contains the instance of a stack. To import Contentstack, refer to the code below:
.svg?format=pjpg&auto=webp){kind=logo}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
.svg?format=pjpg&auto=webp){kind=icon}
import contentstack from '@contentstack/delivery-sdk';
A stack is a repository or a container that holds all the entries/assets of your site. It allows multiple users to create, edit, approve, and publish their content within a single space.
The stack function initializes an instance of the Stack. To initialize a stack execute the following code:
import contentstack from '@contentstack/delivery-sdk'
const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
| Name | Type | Description |
|---|---|---|
apiKey (required) | string | API key of the stack |
deliveryToken (required) | string | Delivery token to retrieve data from the stack |
environment | string | Environment name where content is published |
region | string | DB region of the stack. You can choose from five regions: NA, EU, Azure NA, Azure EU, and GCP NA |
locale | string | Lets you specify which language to use as source content if the entry does not exist in the specified language. |
cacheOptions | CacheOptions | Object to specify the cache details |
When creating custom plugins, through this request, you can pass the details of your custom plugins. This facilitates their utilization in subsequent requests when retrieving details.
To initializing a stack with plugins, refer to the code snippet below:
// custom class for plugin
class CrossStackPlugin {
onRequest (request) {
// add request modifications
return request
}
async onResponse (request, response, data) {
// add response modifications here
return response
}
}
const Stack = Contentstack.stack({
api_key,
delivery_token,
environment,
plugins: [
new CrossStackPlugin(),
new Livepreview()
]
});
The Asset method by default creates an object for all assets of a stack. To retrieve a single asset, specify its UID.
| Name | Type | Description |
|---|---|---|
assetUid | string | UID of the asset |
Example:
const asset = stack.asset(); // For collection of asset
// OR
const asset = stack.asset('assetUid'); // For a single asset with uid 'assetUid'
The ContentType method retrieves all the content types of a stack. To retrieve a single contenttype, specify its UID.
| Name | Type | Description |
|---|---|---|
contentTypeUid | string | UID of the content type |
Example:
const contentType = stack.contentType(); // For collection of contentType
// OR
const contentType = stack.contentType('contentTypeUid'); // For a single contentType with uid 'contentTypeUid'
The setLocale method sets the locale of the API server.
| Name | Type | Description |
|---|---|---|
locale (required) | string | Enter the locale code |
Example:
stack.setLocale('en-155');
The sync method syncs your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates.
| Name | Type | Description |
|---|---|---|
params (required) | ISyncType | ISyncStack | An object that supports ‘locale’, ‘start_date’, ‘content_type_uid’, and ‘type’ queries |
recursive (required) | boolean | Specifies if the sync should be recursive |
Example:
Stack.sync();
Stack.sync({ 'locale': 'en-us'});
Stack.sync({ 'start_date': '2018-10-22'});
Stack.sync({ 'content_type_uid': 'session'});
For initializing sync with a specific type of content:
Stack.sync({ 'type': 'entry_published'});
//Use the type parameter to get a specific type of content. Supports 'asset_published', 'entry_published', 'asset_unpublished', 'entry_unpublished', 'asset_deleted', 'entry_deleted', 'content_type_deleted'
Stack.sync({'pagination_token': '<page_tkn>'});
Stack.sync({'sync_token': '<sync_tkn>'});
In Contentstack, any files (images, videos, PDFs, audio files, and so on) that you upload get stored in your repository for future use. This repository of uploaded files is called assets.
The Asset method by default creates an object for all assets of a stack. To retrieve a single asset, specify its UID.
Example:
import { BaseAsset } from '@contentstack/delivery-sdk'
interface BlogAsset extends BaseAsset {
// other props
}
const asset = await stack.asset('assetUid').fetch<BlogAsset>(); // For a single asset with uid 'assetUid'
| Name | Type | Description |
|---|---|---|
assetUid | string | UID of the asset |
The fetch method retrieves the asset data of the specified asset.
Example:
import { BaseAsset } from '@contentstack/delivery-sdk'
interface BlogAsset extends BaseAsset {
// other custom props
}
const asset = await stack.asset('assetUid').fetch<BlogAsset>();
The includeBranch method includes the branch details in the response.
Example:
const assetResponse = await stack.asset('asset_uid').includeBranch().fetch<BlogAsset>();
The includeDimension method includes the dimensions (height and width) of the image in the result.
Example:
const assetResponse = await stack.asset('asset_uid').includeDimension().fetch<BlogAsset>();
The includeFallback method retrieves the entry in its fallback language.
Example:
const result = await stack.asset('asset_uid').includeFallback().fetch<BlogAsset>();
The locale method retrieves the assets published in that locale.
Example:
const result = await stack.asset('asset_uid').locale('en-us').fetch<BlogAsset>();
The relativeUrls method includes the relative URLs of the asset in the result.
Example:
const result = await stack.asset('asset_uid').relativeUrls().fetch<BlogAsset>();
The version method retrieves the specified version of the asset in the result.
| Name | Type | Description |
|---|---|---|
version (required) | number | Version of the required asset |
Example:
const result = await stack.asset('asset_uid').version(1).fetch<BlogAsset>();
The includeMetadata method includes the metadata for getting metadata content for the entry.
Example:
const result = await stack.asset('asset_uid').includeMetadata().fetch();
The assetQuery method retrieves a collection of assets in a stack.
Example:
const asset = await stack.asset();
The addParam method adds a query parameter to the query.
| Name | Type | Description |
|---|---|---|
paramObj (required) | object | Add key-value pairs |
Example:
import { BaseAsset, FindAsset } from '@contentstack/delivery-sdk'
interface BlogAsset extends BaseAsset {
// other custom props
dimension: {
height: string;
width: string;
};
}
const asset = await stack
.asset()
.addParams({"key": "value"})
.find<BlogAsset>();
The find method retrieves all the assets of the stack.
Example:
const result = await stack.asset().find<BlogAsset>();
The includeBranch method includes the branch details in the result.
Example:
const result = await stack.asset().includeBranch().find<BlogAsset>();
The includeCount method retrieves count and data of all the objects in the result.
Example:
const asset = await stack.asset().includeCount().find<BlogAsset>();
The includeDimension method includes the dimensions (height and width) of the image in the result
Example:
const result = await stack.asset().includeDimension().find<BlogAsset>();
The includeFallback method retrieves the entry in its fallback language.
Example:
const result = await stack.asset().includeFallback().find<BlogAsset>();
The locale method retrieves the asset published in the specified locale.
| Name | Type | Description |
|---|---|---|
locale (required) | string | Locale of the asset |
Example:
const result = await stack.asset().locale('en-us').find<BlogAsset>();
The orderByAscending method sorts the results in ascending order based on the specified field UID.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const asset = await stack.asset().orderByAscending().find<BlogAsset>();
The orderByDescending method sorts the results in descending order based on the specified key.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const asset = await stack.asset().orderByDescending().find<BlogAsset>();
The param method adds query parameters to the URL.
| Name | Type | Description |
|---|---|---|
key (required) | string | Add any param to include in the response |
value (required) | string/number | Add the corresponding value of the param key |
Example:
const asset = await stack.asset().param("key", "value").find<BlogAsset>();
The relativeUrls method includes the relative URLs of all the assets in the result.
Example:
const result = await stack.asset().relativeUrls().find<BlogAsset>();
The removeParam method removes a query parameter from the query.
| Name | Type | Description |
|---|---|---|
key (required) | string | Specify the param key you want to remove |
Example:
const asset = await stack.asset().removeParam("query_param_key").find<BlogAsset>();
The version method retrieves a specific version of the asset in the result.
| Name | Type | Description |
|---|---|---|
version (required) | number | Version number of the asset |
Example:
const result = await stack.asset().version(1).find<BlogAsset>();
The where method filters the results based on the specified criteria.
| Name | Type | Description |
|---|---|---|
fieldUid (required) | string | Specify the field the comparison is made from |
queryOperation (required) | QueryOperationEnum | Specify the comparison criteria |
fields (required) | string | Specify the field the comparison is made to |
Example:
const asset = await stack.asset().where("field_UID", QueryOperation.IS_LESS_THAN, ["field1", "field2"]).find<BlogAsset>();
The includeMetadata method includes the metadata for getting metadata content for the entry.
Example:
const result = await stack.asset().includeMetadata().find<BlogAsset>();
The skip method will skip a specific number of assets in the output.
| Name | Type | Description |
|---|---|---|
skipBy (required) | int | Enter the number of assets to be skipped. |
Example:
const result = await stack.asset().skip(5).find<BlogAsset>();
The limit method will return a specific number of assets in the output.
| Name | Type | Description |
|---|---|---|
limit (required) | int | Enter the maximum number of assets to be returned. |
Example:
const result = await stack.asset().limit(5).find<BlogAsset>();
A content type is the structure or blueprint of a page or a section that your web or mobile property will display. It lets you define the overall schema of this blueprint by adding fields and setting its properties.
Example:
import { BaseContentType } from '@contentstack/delivery-sdk'
interface BlogPost extends BaseContentType {
text: string;
// other custom props
}
const contenttype = await stack.contentType('contentTypeUid').fetch<BlogPost>(); // For a single ContentType with uid 'contentTypeUid'
| Name | Type | Description |
|---|---|---|
contentTypeUid | string | UID of the content type |
The entry method creates an entry object for the specified entry.
| Name | Type | Description |
|---|---|---|
uid | string | UID of the entry |
Example:
const entry = stack.contentType("contentTypeUid").entry("entryUid");
The fetch method retrieves the details for the specified content type.
Example:
const result = await stack.contentType("contentTypeUid").fetch<BlogPost>();
The ContentTypeQuery method retrieves the collection of contentTypes in a stack.
Example:
const contentType = await stack.contentType().find<BlogPost>();
The find method retrieves all the content types of the stack.
Example:
import { BaseContentType, FindContentType } from '@contentstack/delivery-sdk'
interface BlogPostContentType extends BaseContentType {
// custom content type schema
}
const result = await stack.contentType().find<BlogPostContentType>();
The includeGlobalFieldSchema method includes the schema of the global field in the response.
Example:
const contentType = stack.ContentType();
const result = contentType.includeGlobalFieldSchema().find<ContentTypes>();
An Entry is the actual piece of content created using one of the defined content types. To work with a single entry, specify its UID.
Example:
import contentstack from '@contentstack/delivery-sdk'
const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
const entry = await stack.contentType(contentType_uid).entry(entry_uid);
| Name | Type | Description |
|---|---|---|
entryUid | entryUid | UID of the entry |
The fetch method retrieves the details of a specific entry.
Example:
import { BaseEntry } from '@contentstack/delivery-sdk'
interface BlogPostEntry extends BaseEntry {
// custom entry types
}
const result = await stack
.contentType(contentType_uid)
.entry(entry_uid)
.fetch<BlogPostEntry>();
The includeBranch method includes the branch details in the result.
Example:
const result = await stack
.contentType(contentType_uid)
.entry(entry_uid)
.includeBranch()
.fetch<BlogPostEntry>();
The includeFallback method retrieves the entry in its fallback language.
Example:
const result = await stack
.contentType(contentType_uid)
.entry(entry_uid)
.includeFallback()
.fetch<BlogPostEntry>();
The locale method retrieves the entries published in that locale.
| Name | Type | Description |
|---|---|---|
locale (required) | string | Locale of the entry |
Example:
const result = await stack
.contentType(contentType_uid)
.entry(entry_uid)
.locale('en-us')
.fetch<BlogPostEntry>();
The addParam method adds a query parameter to the query.
| Name | Type | Description |
|---|---|---|
paramObj (required) | object | Add key-value pairs |
Example:
import { BaseEntry, FindEntry } from '@contentstack/delivery-sdk'
interface BlogPostEntry extends BaseEntry {
// custom entry types
}
const result = await stack
.contentType(contentType_uid)
.entry()
.addParams({"key": "value"})
.find<BlogPostEntry>();
The except method excludes specific field(s) of an entry.
| Name | Type | Description |
|---|---|---|
fieldUid (required) | string | UID of the field to exclude |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.except("fieldUID")
.find<BlogPostEntry>();
The find method retrieves the details of the specified entry.
Example:
const result = await stack.contentType("contentTypeUid").entry().find<BlogPostEntry>();
The skip method will skip a specific number of entries in the output.
| Name | Type | Description |
|---|---|---|
skipBy (required) | int | Enter the number of entries to be skipped. |
Example:
const result = await stack
.contentType(contentType_uid)
.entry()
.skip(5)
.find<BlogEntry>();
The limit method will return a specific number of entries in the output.
| Name | Type | Description |
|---|---|---|
limit (required) | int | Enter the maximum number of entries to be returned. |
Example:
const result = await stack
.contentType(contentType_uid)
.entry()
.limit(5)
.find<BlogEntry>();
The includeCount method retrieves the count and data of objects in the result.
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.includeCount()
.find<BlogPostEntry>();
The only method selects specific field(s) of an entry.
| Name | Type | Description |
|---|---|---|
fieldUid (required) | string | UID of the field to select |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.only("fieldUID")
.find<BlogPostEntry>();
The orderByAscending sorts the results in ascending order based on the specified field UID.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.orderByAscending()
.find<BlogPostEntry>();
The orderByDescending sorts the results in descending order based on the specified field UID.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.orderByDescending()
.find<BlogPostEntry>();
The param method adds query parameters to the URL.
| Name | Type | Description |
|---|---|---|
key (required) | string | Add any param to include in the response |
value (required) | string | number | Add the corresponding value of the param key |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.param("key", "value")
.find<BlogPostEntry>();
The query method retrieves the details of the entry on the basis of the queries applied.
| Name | Type | Description |
|---|---|---|
queryObj | object | Query in object format |
Example:
const query = stack.contentType("contentTypeUid").entry().query({ "price_in_usd": { "$lt": 600 }});
const result = await query.whereIn("brand").find<BlogPostEntry>();
The removeParam method removes a query parameter from the query.
| Name | Type | Description |
|---|---|---|
key (required) | string | Specify the param key you want to remove |
Example:
const result = await stack
.contentType("contentTypeUid")
.entry()
.removeParam("query_param_key")
.find<BlogPostEntry>();
The where method filters the results based on the specified criteria.
| Name | Type | Description |
|---|---|---|
fieldUid (required) | string | Specify the field the comparison is made from |
queryOperation (required) | QueryOperationEnum | Specify the comparison criteria |
fields (required) | string | Specify the field the comparison is made to |
Example:
const result = await stack
.contentType(contentType_uid)
.entry()
.query()
.where(
"field_UID",
QueryOperation.IS_LESS_THAN,
["field1", "field2"])
.find<BlogPostEntry>();
The includeMetadata method includes the metadata for getting metadata content for the entry.
Example:
const result = await stack
.contentType('contentType_uid')
.entry('entry_uid')
.includeMetadata()
.fetch<BlogEntry>();
The includeEmbeddedItems method includes embedded objects (Entry and Assets) along with entry details
Example:
const result = await stack
.contentType(contentType_uid)
.entry('entry_uid')
.includeEmbeddedItems()
.fetch<BlogEntry>();
The includeContentType method includes the details of the content type along with the Entry details.
Example:
const result = await stack
.contentType(contentType_uid)
.entry('entry_uid')
.includeContentType()
.fetch<BlogEntry>();
The includeReference method retrieves the content of the referred entries in your response.
| Name | Type | Description |
|---|---|---|
referenceFieldUid (required) | string | UID of the reference field to include |
Example:
const query = stack.contentType(contentType_uid).entry();
const result = await query
.includeReference("brand")
.find<BlogPostEntry>();
Variants are different versions of content designed to meet specific needs or target audiences. This feature allows content editors to create multiple variations of a single entry, each customized for a particular variant group or purpose.
When Personalize creates a variant in the CMS, it assigns a "Variant Alias" to identify that specific variant. When fetching entry variants using the Delivery API, you can pass variant aliases in place of variant UIDs in the x-cs-variant-uid header.
Single Variant: This method retrieves the details of a specific entry variant.
Example:
import contentstack from '@contentstack/delivery-sdk';
const Stack = contentstack.stack
({'api_key': 'api_key', 'delivery_token': 'delivery_token', 'environment': 'environment'});
const result = await Stack
.contentType('content_type_uid')
.entry('entry_uid')
.variants('variant_uid/variant_alias')
.fetch();
Layering variants: This method retrieves the details of entry variants based on the applied query
Example:
import contentstack from '@contentstack/delivery-sdk';
const Stack = contentstack.stack
({'api_key': 'api_key', 'delivery_token': 'delivery_token', 'environment': 'environment'});
const result = await Stack
.contentType('content_type_uid')
.entry('entry_uid')
.variants(['variant_uid1/variant_alias1','variant_uid2/variant_alias2'])
.fetch();
The initializer creates a Query object and provides support for all the different types of search queries.
Example:
const query = stack.contentType("contentTypeUid").Entry().query();
The addParam method adds a query parameter to the query.
| Name | Type | Description |
|---|---|---|
paramObj (required) | string | Add key-value pairs |
Example:
import { BaseEntry, FindEntry } from '@contentstack/delivery-sdk'
interface BlogPostEntry extends BaseEntry {
// custom entry types
}
const query = stack.contentType(contentType_uid).entry().query();
const result = await query
.addParams({"key": "value"})
.find<BlogPostEntry>();
The addQuery method adds multiple query parameters to the query.
| Name | Type | Description |
|---|---|---|
key (required) | string | Add filter query key |
value (required) | string | number | Add the corresponding value to the filter query key |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query
.addQuery("query_param_key", "query_param_value")
.find<BlogPostEntry>();
The find method retrieves the details of the specified entry.
Example:
const result = await stack
.contentType("contentType1Uid")
.entry()
.query()
.find<BlogPostEntry>();
The includeCount method retrieves count and data of objects in the result.
Example:
const query = stack.contentType(contentType_uid).entry().query();
const result = await query.includeCount().find<BlogPostEntry>();
The orderByAscending method sorts the results in ascending order based on the specified field UID.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const query = stack.contentType(contentType_uid).entry().query();
const result = await query
.orderByAscending()
.find<BlogPostEntry>();
The orderByDescending method sorts the results in descending order based on the specified key.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field UID to sort the results |
Example:
const query = stack.contentType(contentType_uid).entry().query();
const result = await query
.orderByDescending()
.find<BlogPostEntry>();
The param method adds query parameters to the URL.
| Name | Type | Description |
|---|---|---|
key (required) | string | Add any param to include in the response |
value (required) | string | number | Add the corresponding value of the param key |
Example:
const query = stack.contentType(contentType_uid).entry().query();
const result = await query
.param("key", "value")
.find<BlogPostEntry>();
The queryOperator method retrieves the entries as per the given operator.
| Name | Type | Description |
|---|---|---|
queryType (required) | QueryOperatorEnum | Type of query operator to apply |
queryObjects (required) | Query[] | Query instances to apply the query to |
Example:
import contentstack, { QueryOperation, QueryOperator } from '@contentstack/delivery-sdk'
const stack = contentstack.stack("apiKey", "deliveryKey", "environment");
const query = stack.contentType("contentType1Uid").entry().query();
const subQuery1 = stack
.contentType("contentType2Uid")
.query()
.where(
"price",
QueryOperation.IS_LESS_THAN,
fields=90);
const subQuery2 = stack
.contentType("contentType3Uid")
.query()
.where(
"discount",
QueryOperation.INCLUDES,
fields=[20, 45]);
query.queryOperator(QueryOperator.AND, subQuery1, subQuery2)
Const result = await query.find<BlogPostEntry>();
The removeParam method removes a query parameter from the query.
| Name | Type | Description |
|---|---|---|
key (required) | string | Specify the param key you want to remove |
Example:
const query = stack.contentType(contentType_uid).entry().query();
const result = await query
.removeParam("query_param_key")
.find<BlogPostEntry>();
The where method filters the results based on the specified criteria.
| Name | Type | Description |
|---|---|---|
fieldUid (required) | string | Specify the field the comparison is made from |
queryOperation (required) | QueryOperationEnum | Specify the comparison criteria |
fields (required) | string | strings[] | Specify the field the comparison is made to |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query
.where(
"field_UID",
QueryOperation.IS_LESS_THAN,
["field1", "field2"])
.find<BlogPostEntry>();
The whereIn method retrieves the entries that meet the query conditions made on referenced fields.
| Name | Type | Description |
|---|---|---|
referenceUid (required) | string | UID of the reference field to query |
queryInstance (required) | Query | Query instance to include in the where clause |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
query.whereIn("brand");
const result = await query.find<BlogPostEntry>();
The whereNotIn method retrieves the entries that do not meet the query conditions made on referenced fields.
| Name | Type | Description |
|---|---|---|
referenceUid (required) | string | UID of the reference field to query |
queryInstance (required) | Query | Query instance to include in the where clause |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
query.whereNotIn("brand");
const result = await query.find<BlogPostEntry>();
The skip method will skip a specific number of entries in the output.
| Name | Type | Description |
|---|---|---|
skipBy (required) | int | Enter the number of entries to be skipped. |
Example:
const result = await stack
.contentType(contentType_uid)
.entry()
.query()
.skip(5)
.find<BlogEntry>();
The limit method will return a specific number of entries in the output.
| Name | Type | Description |
|---|---|---|
limit (required) | int | Enter the maximum number of entries to be returned. |
Example:
const result = await stack
.contentType(contentType_uid)
.entry()
.query()
.limit(5)
.find<BlogEntry>();
The or method retrieves the entries that meet either of the conditions specified.
| Name | Type | Description |
|---|---|---|
queries (required) | array | Array of query objects or raw queries |
Example:
const query1 = stack.contentType('contenttype_uid').entry().query().containedIn('fieldUID', ['value']);
const query2 = stack.contentType('contenttype_uid').entry().query().where('fieldUID', QueryOperation.EQUALS, 'value2');
const query = await stack.contentType('contenttype_uid').entry().query().or(query1, query2).find<BlogPostEntry>();
The and method retrieves the entries that meet all the specified conditions.
| Name | Type | Description |
|---|---|---|
queries (required) | array | Array of query objects or raw queries |
Example:
const query1 = stack.contentType('contenttype_uid').entry().query().containedIn('fieldUID', ['value']);
const query2 = stack.contentType('contenttype_uid').entry().query().where('fieldUID', QueryOperation.EQUALS, 'value2');
const query = await stack.contentType('contenttype_uid').entry().query().and(query1, query2).find<BlogPostEntry>();
The containedIn method retrieves the entries that contain the conditions specified.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.containedIn('fieldUid', ['value1', 'value2']).find();
The notContainedIn method retrieves the entries where the specified conditions are absent.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.notContainedIn('fieldUid', ['value1', 'value2']).find();
The equalTo method retrieves entries that match the specified conditions exactly.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = await stack.contentType('contenttype_uid').entry().query().equalTo('fieldUid', 'value').find<BlogPostEntry>();
The exists method retrieves the entries that satisfy the specified condition of existence.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.exists('fieldUid').find();
The notExists method retrieves entries where the specified conditions are not met.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.notExists('fieldUid').find();
The getQuery method retrieves the entries as per the specified query.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.query({'brand': {'$nin_query': {'title': 'Apple Inc.'}}}).getQuery();
// OR
const asset = await stack.asset().query({'brand': {'$nin_query': {'title': 'Apple Inc.'}}}).getQuery();
The greaterThan method retrieves the entries that are greater than the specified condition.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().greaterThan('fieldUid', 'value').find<BlogPostEntry>();
The greaterThanOrEqualTo method retrieves entries that meet the specified condition of being greater than or equal to a certain value.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().greaterThanOrEqualTo('fieldUid', 'value').find<BlogPostEntry>();
The lessThan method retrieves the entries that are less than the specified condition.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().lessThan('fieldUid', 'value').find<BlogPostEntry>();
The lessThanOrEqualTo method retrieves entries that meet the specified condition of being less than or equal to a certain value.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().lessThanOrEqualTo('fieldUid', 'value').find<BlogPostEntry>();
The referenceIn method retrieves the entries that are referenced.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the reference field |
value (required) | object | RAW (JSON) queries |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().referenceIn('reference_uid', query).find<BlogPostEntry>();
The referenceNotIn method retrieves the entries where the referenced items are not included.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the reference field |
value (required) | object | RAW (JSON) queries |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().referenceNotIn('reference_uid', query).find<BlogPostEntry>();
The regex method retrieves entries that match a specified regular expression pattern.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
value (required) | array | Array of values that are to be used to match or compare |
options (required) | any | Match or compare value in entry |
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const result = await query.regex('title','^Demo').find();
// OR
const result = await query.regex('title','^Demo', 'i').find<BlogPostEntry>();
The search method retrieves the entries that match the specified search criteria.
| Name | Type | Description |
|---|---|---|
key (required) | string | UID of the field |
Example:
const entryQuery = await stack.contentType('contenttype_uid').query().search('key').find<BlogPostEntry>();
The tags method fetches the entries that are associated with specific tags.
| Name | Type | Description |
|---|---|---|
value (required) | array | Array of tags |
Example:
const query = stack.contentType('contenttype_uid').query().where('title', QueryOperation.EQUALS, 'value');
const entryQuery = await stack.contentType('contenttype_uid').query().tags(['tag1']).find<BlogPostEntry>();
Taxonomy helps you categorize pieces of content within your stack to facilitate easy navigation, search, and retrieval of information.
Note: All methods in the Query section are applicable for taxonomy-based filtering as well.
The equalAndBelow operation retrieves all entries for a specific taxonomy that match a specific term and all its descendant terms, requiring only the target term.
| Name | Type | Description |
|---|---|---|
key (required) | string | Enter the UID of the taxonomy |
value (required) | string | Enter the UID of the term |
levels | int | Enter the level |
const data = await stack
.taxonomy()
.where(
'taxonomies.one',
TaxonomyQueryOperation.EQ_BELOW,
'term_one',
{"levels": 1} // optional
)
.find<TEntries>()
The below operation retrieves all entries for a specific taxonomy that match all of their descendant terms by specifying only the target term and a specific level.
Note: If you don't specify the level, the default behavior is to retrieve terms up to level 10.
| Name | Type | Description |
|---|---|---|
key (required) | string | Enter the UID of the taxonomy |
value (required) | string | Enter the UID of the term |
levels | int | Enter the level |
const data = await stack
.taxonomy()
.where(
'taxonomies.one',
TaxonomyQueryOperation.BELOW,
'term_one',
{"levels": 1} // optional
)
.find<TEntries>()
The equalAndAbove operation retrieves all entries for a specific taxonomy that match a specific term and all its ancestor terms, requiring only the target term and a specified level
Note: If you don't specify the level, the default behavior is to retrieve terms up to level 10.
| Name | Type | Description |
|---|---|---|
key (required) | string | Enter the UID of the taxonomy |
value (required) | string | Enter the UID of the term |
levels | int | Enter the level |
const data = await stack
.taxonomy()
.where(
'taxonomies.one',
TaxonomyQueryOperation.EQ_ABOVE,
'term_one',
{"levels": 1} // optional
)
.find<TEntries>()
The equalAndAbove operation retrieves all entries for a specific The above operation retrieves all entries for a specific taxonomy that match only the parent terms of a specified target term, excluding the target term itself and a specified level.
Note: If you don't specify the level, the default behavior is to retrieve terms up to level 10.
| Name | Type | Description |
|---|---|---|
key (required) | string | Enter the UID of the taxonomy |
value (required) | string | Enter the UID of the term |
levels | int | Enter the level |
const data = await stack
.taxonomy()
.where(
'taxonomies.one',
TaxonomyQueryOperation.ABOVE,
'term_one',
{"levels": 1} // optional
)
.find<TEntries>()
A Global field is a reusable field (or group of fields) that you can define once and reuse in any content type within your stack. This eliminates the need (and thereby time and efforts) to create the same set of fields repeatedly in multiple content types.
Example:
const globalField = stack.globalField('global_field_uid'); // For a single globalField with uid 'global_field_uid'
| Name | Type | Description |
|---|---|---|
globalFieldUid | string | UID of the Global field |
The find method retrieves all the assets of the stack.
Example:
import { BaseGlobalField, FindGlobalField } from '@contentstack/delivery-sdk'
interface ImageField extends BaseGlobalField {
format: string
// other props
}
const result = await stack
.globalField()
.find<ImageField>();
The fetch method retrieves the global field data of the specified global field.
Example:
import { BaseGlobalField } from '@contentstack/delivery-sdk'
const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
interface ImageField extends BaseGlobalField {
format: string
// other props
}
const result = await stack
.globalField('global_field_uid')
.fetch<ImageField>();
The includeBranch method includes the branch details in the result for single or multiple global fields.
Example:
const result = await stack
.globalField('global_field_uid')
.includeBranch()
.find<ImageField>();
In a single instance, a query will retrieve only the first 100 items in the response. You can paginate and retrieve the rest of the items in batches using the skip and limit parameters in subsequent requests.
Example:
const query = stack.contentType("contentTypeUid").entry().query();
const pagedResult = await query
.paginate()
.find<BlogPostEntry>();
// OR
const pagedResult = await query
.paginate({ skip: 20, limit: 20 })
.find<BlogPostEntry>();
The next method retrieves the next set of response values and skips the current number of responses.
Example:
const pagedResult = await query
.paginate()
.find<BlogPostEntry>();
const nextPageResult = await query.next().find<BlogPostEntry>();
The previous method retrieves the previous set of response values and skips the current number of responses.
Example:
const pagedResult = await query
.paginate()
.find<BlogPostEntry>();
const prevPageResult = await query
.previous()
.find<BlogPostEntry>();
Image transformations can be performed on images by specifying the desired parameters. The parameters control the specific transformations that will be applied to the image.
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().bgColor('cccccc');
const transformURL = url.transform(transformObj);
The auto method enables the functionality that automates certain image optimization features.
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().auto();
const transformURL = url.transform(transformObj);
The bgColor method sets a background color for the given image.
| Name | Type | Description |
|---|---|---|
color (required) | string | Color of the background |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().bgColor('cccccc');
const transformURL = url.transform(transformObj);
The blur method allows you to decrease the focus and clarity of a given image.
| Name | Type | Description |
|---|---|---|
blurValue (required) | number | Set the blur intensity between 1 to 1000 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().blur(10);
const transformURL = url.transform(transformObj);
The brightness method enables the functionality that automates certain image optimization features.
| Name | Type | Description |
|---|---|---|
brightnessValue (required) | number | Set the brightness of the image between -100 to 100 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().brightness(80.50);
const transformURL = url.transform(transformObj);
The canvas method allows you to increase the size of the canvas that surrounds an image.
| Name | Type | Description |
|---|---|---|
canvasBy | CanvasByEnum | Specifies what params to use for creating canvas - DEFAULT, ASPECTRATIO, REGION, OFFSET |
height (required) | string | number | Sets height of the canvas |
width (required) | string | number | Sets width of the canvas |
xval | string | number | Defines the X-axis position of the top left corner or horizontal offset |
yval | string | number | Defines the Y-axis position of the top left corner or vertical offset |
Example 1:
const url = 'www.example.com';
const transformObj = new ImageTransform().canvas({ width: 100, height: 200 });
const transformURL = url.transform(transformObj);
Example 2:
const url = 'www.example.com';
const transformObj = new ImageTransform().canvas({ width: 200, height: 300, canvasBy: CanvasByEnum.OFFSET, xval: 100, yval: 150 });
const transformURL = url.transform(transformObj);
The contrast method enables the functionality that automates certain image optimization features.
| Name | Type | Description |
|---|---|---|
contrastValue (required) | number | Set the contrast of the image between -100 to 100 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().contrast(-80.99);
const transformURL = url.transform(transformObj);
The crop method allows you to remove pixels from an image by adjusting the height and width in the percentage value or aspect ratio.
| Name | Type | Description |
|---|---|---|
cropBy | CropByEnum | Specify the CropBy type using values DEFAULT, ASPECTRATIO, REGION, or OFFSET. |
width (required) | string | number | Specify the width to resize the image to. The value can be in pixels (for example, 400) or in percentage (for example, 0.60 OR '60p') |
height (required) | string | number | Specify the height to resize the image to. The value can be in pixels (for example, 400) or in percentage (for example, 0.60 OR '60p') |
xval (required) | string | number | For the CropBy Region, specify the X-axis position of the top left corner of the crop. For CropBy Offset, specify the horizontal offset of the crop region. |
yval | string | number | For CropBy Region, specify the Y-axis position of the top left corner of the crop. For CropBy Offset, specify the vertical offset of the crop region. |
safe | boolean | Ensures that the output image never returns an error due to the specified crop area being out of bounds. The output image is returned as an intersection of the source image and the defined crop area. |
smart | boolean | Ensures crop is done using content-aware algorithms. Content-aware image cropping returns a cropped image that automatically fits the defined dimensions while intelligently including the most important components of the image. |
Example 1:
const url = 'www.example.com';
const transformObj = new ImageTransform().crop({ width: 100, height: 200 });
const transformURL = url.transform(transformObj);
Example 2:
const url = 'www.example.com';
const transformObj = new ImageTransform().crop({ width: 2, height: 3, cropBy: CropByEnum.ASPECTRATIO });
const transformURL = url.transform(transformObj);
Example 3:
const url = 'www.example.com';
const transformObj = new ImageTransform().crop({ width: 200, height: 300, cropBy: CropByEnum.REGION, xval: 100, yval: 150 });
const transformURL = url.transform(transformObj);
Example 4:
const url = 'www.example.com';
const transformObj = new ImageTransform().crop({ width: 200, height: 300, cropBy: CropByEnum.OFFSET, xval: 100, yval: 150 });
const transformURL = url.transform(transformObj);
The dpr method lets you deliver images with appropriate size to devices that come with a defined device pixel ratio.
| Name | Type | Description |
|---|---|---|
dprValue | number | Specify the device pixel ratio. The value should range between 1-10000 or 0.0 to 9999.999 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().resize({ width: 300, height: 500 }).dpr(10);
const transformURL = url.transform(transformObj);
The fit method enables you to fit the given image properly within the specified height and width.
| Name | Type | Description |
|---|---|---|
type | FitByEnum | Specifies fit type (Bounds or Crop) |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().resize({ width: 200, height: 200 }).fit(FitByEnum.BOUNDS);
const transformURL = url.transform(transformObj);
The format method lets you convert a given image from one format to another.
| Name | Type | Description |
|---|---|---|
format | FitByEnum | Specify the format |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().format(FormatEnum.PJPG);
const transformURL = url.transform(transformObj);
The frame method retrieves the first frame from an animated GIF (Graphics Interchange Format) file that comprises a sequence of moving images.
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().frame();
const transformURL = url.transform(transformObj);
The orient method allows you to rotate or flip an image in any direction.
| Name | Type | Description |
|---|---|---|
orientType (required) | FitByEnum | Type of Orientation. Values are DEFAULT, FLIP_HORIZONTAL, FLIP_HORIZONTAL_VERTICAL, FLIP_VERTICAL, FLIP_HORIZONTAL_LEFT, RIGHT, FLIP_HORIZONTAL_RIGHT, LEFT. |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().orient(Orientation.FLIP_HORIZONTAL);
const transformURL = url.transform(transformObj);
The overlay method lets you place one image over another by specifying the relative URL of the image.
| Name | Type | Description |
|---|---|---|
relativeURL (required) | string | URL of the image to overlay on base image |
align | OverlayAlignEnum | Lets you define the position of the overlay image. Accepted values are TOP, BOTTOM, LEFT, RIGHT, MIDDLE, CENTER |
repeat | OverlayRepeatEnum | Lets you define how the overlay image will be repeated on the given image. Accepted values are X, Y, BOTH |
width | string | number | Lets you define the width of the overlay image. For pixels, use any whole number between 1 and 8192. For percentages, use any decimal number between 0.0 and 0.99 |
height | string | number | Lets you define the height of the overlay image. For pixels, use any whole number between 1 and 8192. For percentages, use any decimal number between 0.0 and 0.99 |
pad | number | Lets you add extra pixels to the edges of an image. This is useful if you want to add whitespace or border to an image |
Example 1:
const url = 'www.example.com';
const transformObj = new ImageTransform().overlay({ relativeURL: overlayImgURL });
const transformURL = url.transform(transformObj);
Example 2:
const url = 'www.example.com';
const transformObj = new ImageTransform().overlay({ relativeURL: overlayImgURL, align: OverlayAlignEnum.BOTTOM });
const transformURL = url.transform(transformObj);
Example 3:
const url = 'www.example.com';
const transformObj = new ImageTransform().overlay({
relativeURL: overlayImgURL,
align: OverlayAlignEnum.BOTTOM,
repeat: OverlayRepeatEnum.Y,
width: '50p',
});
const transformURL = url.transform(transformObj);
The padding method lets you add extra pixels to the edges of an image's border or add whitespace.
| Name | Type | Description |
|---|---|---|
padding (required) | number | padding value in pixels or percentages |
Example 1:
const url = 'www.example.com';
const transformObj = new ImageTransform().padding([25, 50, 75, 90]);
const transformURL = url.transform(transformObj);
Example 2:
const url = 'www.example.com';
const transformObj = new ImageTransform().padding(50);
const transformURL = url.transform(transformObj);
The quality method lets you control the compression level of images that have lossy file format.
| Name | Type | Description |
|---|---|---|
qualityNum (required) | number | Quality range: 1 - 100 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().quality(50);
const transformURL = url.transform(transformObj);
The resize method lets you resize the image in terms of width, height, upscaling the image.
| Name | Type | Description |
|---|---|---|
width | number | Specifies the width to resize the image to. The value can be in pixels (for example, 400) or in percentage (for example, 0.60 OR '60p') |
height | string | number | Specifies the height to resize the image to.The value can be in pixels (for example, 400) or in percentage (for example, 0.60 OR '60p') |
disable | string | The disable parameter disables the functionality that is enabled by default. As of now, there is only one value, i.e., upscale, that you can use with the disable parameter. |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().resize({ width: 200, height: 200, disable: 'upscale' });
const transformURL = url.transform(transformObj);
The resizeFilter method allows you to increase or decrease the number of pixels in a given image.
| Name | Type | Description |
|---|---|---|
type (required) | ResizeFilterEnum | Types of Filter to apply. Values are NEAREST, BILINEAR, BICUBIC, LANCZOS2, LANCZOS3. |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().resize({ width: 500, height: 550 }).resizeFilter(ResizeFilterEnum.NEAREST);
const transformURL = url.transform(transformObj);
The saturation method allows you to increase or decrease the intensity of the colors in a given image.
| Name | Type | Description |
|---|---|---|
saturationValue (required) | number | To set the saturation of image between -100 to 100 |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().saturation(-80.99);
const transformURL = url.transform(transformObj);
The sharpen method allows you to increase the definition of the edges of objects in an image.
| Name | Type | Description |
|---|---|---|
amount (required) | number | Specifies the amount of contrast to be set for the image edges between the range [0-10] |
radius (required) | number | Specifies the radius of the image edges between the range [1-1000] |
threshold (required) | number | Specifies the range of image edges that need to be ignored while sharpening between the range [0-255] |
Example:
const url = 'www.example.com';
const transformObj = new ImageTransform().sharpen(5, 1000, 2);
const transformURL = url.transform(transformObj);
The trim method lets you trim an image from the edges.
| Name | Type | Description |
|---|---|---|
trimValue (required) | number | number[] | Specifies values for top, right, bottom, and left edges of an image. |
Example 1:
const url = 'www.example.com';
const transformObj = new ImageTransform().trim([25, 50, 75, 90]);
const transformURL = url.transform(transformObj);
Example 2:
const url = 'www.example.com';
const transformObj = new ImageTransform().trim([25, 50, 25]);
const transformURL = url.transform(transformObj);
Example 3:
const url = 'www.example.com';
const transformObj = new ImageTransform().trim(50);
const transformURL = url.transform(transformObj);