DataSync Filesystem SDK API Reference
The Contentstack DataSync Filesystem SDK enables developers to synchronize and query Contentstack data directly from a local filesystem, optimizing content delivery and access.
Additional Resource: To know more about DataSync Filesystem SDK, refer to the Get Started with DataSync Filesystem SDK documentation.
Contentstack
The Contentstack module creates an instance of the Contentstack class, which serves as the entry point for initializing a stack.
Stack
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 instance provides access to all query methods for fetching entries, assets, and content type data from the local filesystem.
Name | Type | Description |
---|---|---|
baseDir | string | Base directory of the folder where data is stored |
locale | string | Default locale to use when .language() is not specified in a query |
referenceDepth | number | The default nested reference field depth considered when calling .includeReferences(). This can be overridden by passing a numerical argument to .includeReferences(n) |
projections | object | Keys that by default would be removed from results. Pass key: 0 to remove, key: 1 to override the existing |
Example:
import { Contentstack } from "@contentstack/datasync-filesystem-sdk"; const config = { contentStore: { baseDir: './_contents', defaultSortingField: 'updated_at', locale: 'en-us', projections: { _content_type_uid: 0, }, referenceDepth: 2, }, } const Stack = Contentstack.Stack(config);
Global
The Global class provides a collection of methods that define and execute complex queries in the Datasync Filesystem SDK. Use it to filter, sort, and retrieve content from the local filesystem based on specific conditions.
and
The and method combines multiple query conditions using a logical AND operator and returns entries that meet all the mentioned conditions.
Name | Type | Description |
---|---|---|
queries (required) | object | Filters defining the conditions to match the entries |
Example:
Stack .contentType('example') .entries() .and([{ title: 'John' }, { age: 30 } ]) .find() .then((result) => { // Queries local filesystem for entries with title "John" and age 30 }) .catch((error) => { // Handle errors that occur during the query execution })
ascending
The ascending method sorts the fetched entries in ascending order based on the specified field.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID used to sort the entries |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.ascending('created_at').find() data.then((result) => { // ‘result’ contains the list of entries which is sorted in ascending order on the basis of ‘created_at’. }).catch((error) => { // Handle errors that occur during the query execution })
asset
The asset method retrieves a single asset by its UID.
Name | Type | Description |
---|---|---|
uid (required) | string | UID of the asset |
Example:
Stack.asset('uid').find(); // or Stack.asset().find();
assets
The assets method retrieves details of all assets.
Example:
Stack.assets().find();
connect
The connect method establishes a connection to the filesystem with optional configuration overrides.
Name | Type | Description |
---|---|---|
overrides (required) | object | Provides optional overrides or filesystem-specific settings |
Example:
Stack.connect({ overrides }) .then((baseDir) => { // Connection established }) .catch((error) => { // Handle errors related to filesystem connection });
contentType
The contentType method specifies the content type to query on.
Name | Type | Description |
---|---|---|
uid (required) | string | UID of the content type |
Example:
Stack.contentType('example').find() .then((result) => { // returns entries filtered based on 'example' content type }) .catch((error) => { // Handle errors that occur during the query execution })
contentTypes
The contentTypes method retrieves schemas of all content types.
Example:
Stack.contentTypes().find()
count
The count method returns the total number of entries matching the query.
Example:
const query = Stack.contentType('example').entries().count().find() query.then((result) => { // returns 'example' content type's entries }).catch(error) => { // Handle errors that occur during the query execution })
descending
The descending method sorts the fetched entries in descending order based on the specified field.
Name | Type | Description |
---|---|---|
uid (required) | string | Field UID used to sort the entries |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.descending('created_at').find() data.then((result) => { // ‘result’ contains the list of entries which is sorted in descending order on the basis of ‘created_at’. }).catch((error) => { // Handle errors that occur during the query execution })
entry
The entry method retrieves a single entry by its UID from the specified content type.
Name | Type | Description |
---|---|---|
uid | string | The UID of the entry |
Example:
Stack.contentType('example').entry('bltabcd12345').find(); // or Stack.contentType('example').entry().find();
except
The except method accepts an array of field UIDs. Only the fields specified in the array will be excluded from the result set.
Name | Type | Description |
---|---|---|
result (required) | string | The field to evaluate |
Example:
const query = Stack.contentType('example').entries().except(['title','uid']).find() query.then((result) => { // ‘result’ contains a list of entries without field title and uid }).catch((error) => { // Handle errors that occur during the query execution })
excludeReferences
The excludeReferences method excludes all references of the entries being scanned.
Example:
Stack.contentType('example') .entries() .excludeReferences() .find() .then((result) => { // ‘result’ entries without references }).catch((error) => { // Handle errors that occur during the query execution })
entries
The entries method retrieves entries from the specified content type.
Example:
Stack.contentType('example').entries().find();
exists
The exists method retrieves entries if the value of the specified field exists.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.exists('featured').find() data.then((result) => { // ‘result’ contains the list of entries in which "featured" exists. }).catch((error) => { // Handle errors that occur during the query execution })
findOne
The findOne method queries the local database using the built or provided query and returns a single matching entry, asset, or content type object. It processes the data, applies filters, and resolves references before returning the result.
Name | Type | Description |
---|---|---|
query | object | A query object that overrides all previously built query conditions |
Example:
Stack.contentType('blog') .entries() .findOne()
find
The find method queries the local database using the built or optionally provided query object. It processes the data, applies filters, and resolves references before returning the result.
Name | Type | Description |
---|---|---|
query | object | A query object that overrides all previously built query conditions |
Example:
Stack.contentType('blog').entries().find() .then((result) => { // returns blog content type's entries }) .catch((error) => { // Handle errors that occur during the query execution })
getQuery
The getQuery method returns the query object built with the applied conditions and filters.
Example:
Stack.contentType('example') .equalTo('title','Demo') .getQuery() .find()
greaterThan
The greaterThan method retrieves entries where the value of the specified field is greater than the given number.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.greaterThan('created_at','2015-03-12').find() data.then((result) => { // result contains the data of entries where the 'created_at' date will be greaterthan '2015-03-12' }).catch((error) => { // Handle errors that occur during the query execution })
greaterThanOrEqualTo
The greaterThanOrEqualTo method retrieves entries where the field's value is greater than or equal to the specified number.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.greaterThanOrEqualTo('created_at','2015-03-12').find() data.then((result) => { // result contains the data of entries where the 'created_at' date will be greaterThan or equalto '2015-03-12' }).catch((error) => { // Handle errors that occur during the query execution })
include
The include method includes a specific field in the returned result.
Name | Type | Description |
---|---|---|
key (required) | string | UID of the field |
Example:
Stack.contentType('example') .entries() .include(['authors','categories']) .find()
includeCount
The includeCount method returns the total count of matching entries along with the result set.
Example:
Stack.contentType('example') .entries() .includeCount() .find()
includeContentType
The includeContentType method includes the full content type schema along with each entry in the response.
Example:
Stack.contentType('example') .entries() .includeContentType() .find() .then((result) => { // Expected result { entries: [ { ..., }, ], content_type_uid: 'example', locale: 'en-us', content_type: { ..., // Content type example's schema } } }).catch((error) => { // Handle errors that occur during the query execution })
includeReference
The includeReference method includes referenced entries or assets in the response.
Name | Type | Description |
---|---|---|
depth | number | Overrides the default reference depth of 4 |
Example:
Stack.contentType('example') .entries() .includeReference() .find()
language
The language method sets the locale to be used when querying entries.
Name | Type | Description |
---|---|---|
languageCode (required) | string | Language to query on |
Example:
Stack.contentType('blog').entries().language('fr-fr').find();
lessThan
The lessThan method retrieves entries where the value of the specified field is less than the given number.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.lessThan('created_at','2015-06-22').find() data.then((result) => { // result contains the data who's 'created_at date' is less than '2015-06-22' }).catch((error) => { // Handle errors that occur during the query execution })
lessThanOrEqualTo
The lessThanOrEqualTo method retrieves entries where the field's value is less than or equal to the specified number.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.lessThanOrEqualTo('created_at','2015-06-22').find() data.then((result) => { // result contain the data of entries where the 'created_at' date will be less than or equalto '2015-06-22'. }).catch((error) => { // Handle errors that occur during the query execution })
limit
The limit method sets the maximum number of entries to retrieve.
Name | Type | Description |
---|---|---|
limit (required) | number | Maximum number of entries to be returned |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.limit(10).find() data.then((result) => { // result contains the limited number of entries }).catch((error) => { // Handle errors that occur during the query execution })
notContainedIn
The notContainedIn method retrieves entries where the specified field's value does not match any in the given array.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.notContainedIn('title', ['Demo', 'Welcome']).find() data.then((result) => { // 'result' contains the list of entries where value of the title field should not be either "Demo" or ‘Welcome’ }).catch((error) => { // Handle errors that occur during the query execution })
notEqualTo
The notEqualTo method retrieves entries where the field’s value does not equal the specified value.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.notEqualTo('title','Demo').find() data.then((result) => { // ‘result’ contains the list of entries where value of the ‘title’ field will not be 'Demo'. }).catch((error) => { // Handle errors that occur during the query execution })
only
The only method limits the returned fields in the result to the ones specified.
Name | Type | Description |
---|---|---|
result (required) | string | The field to evaluate |
Example:
const query = Stack.contentType('example').entries().only(['title','uid']).find() query.then((result) => { // ‘result’ contains a list of entries with field title and uid only }).catch((error) => { // Handle errors that occur during the query execution })
or
The or method combines multiple conditions using the logical OR operator.
Name | Type | Description |
---|---|---|
queries (required) | object | Array of Query objects or raw query conditions |
Example:
Stack .contentType('example') .entries() .or([{ title: 'John'}, { title: 'Jane'}]) .find() .then((result) => { // Queries local filesystem for entries with title "John" and age 30 }) .catch((error) => { // Handle errors that occur during the query execution })
query
The query method initializes a query builder for the selected content type or resource.
Name | Type | Description |
---|---|---|
userQuery (required) | object | A raw JSON query object to define custom filters |
Example:
Stack.contentType('example').entries().query({"authors.name": "John Doe"}).find() .then((result) => { // returns entries, who's reference author's name equals "John Doe" }) .catch((error) => { // Handle errors that occur during the query execution })
queryReferences
The queryReferences method allows you to perform a query on referenced entries.
Name | Type | Description |
---|---|---|
query (required) | Any | Query filter to apply on the referenced entries |
Example:
Stack.contentType('blog') .entries() .includeReference() // This would include all references of the content type .queryReferences({"authors.name": "John Doe"}) .find()
referenceDepth
The referenceDepth method is used alongside .includeReferences() to override the default reference resolution depth of 2. This allows you to resolve deeply nested references—e.g., if A → B → C → D, all levels down to D will be included in the result.
Name | Type | Description |
---|---|---|
depth (required) | number | Level of nested references to be fetched |
Example:
Stack.contentType('blog') .entries() .includeReferences() .referenceDepth(4) .find()
regex
The regex method retrieves entries where the specified field matches the given regular expression.
Name | Type | Description |
---|---|---|
key (required) | string | Field UID to filter |
value (required) | Any[] | An array of values to match against |
options | string | Value to match or compare against the entry field |
Example:
let blogQuery = Stack.contentType('example').entries() blogQuery.regex('title','^Demo').find() //regex without options //or blogQuery.regex('title','^Demo', 'i').find() //regex with options
schema
The schema method fetches the schema definition of a content type.
Name | Type | Description |
---|---|---|
uid | string | Fetches the schema for the content type with the given UID |
Example:
Stack.schema(uid?: string).find()
schemas
The schemas method fetches the schemas definition of a content type.
Example:
Stack.schemas.find()
skip
The skip method skips a given number of results from the beginning of the result set.
Name | Type | Description |
---|---|---|
skip (required) | number | Skips the specified number of entries in the result set |
Example:
let blogQuery = Stack.contentType('example').entries() let data = blogQuery.skip(5).find() data.then((result) => { //result }).catch((error) => { // Handle errors that occur during the query execution })
tags
The tags method retrieves all unique tags present in the content entries.
Name | Type | Description |
---|---|---|
value (required) | Array | Entries/Assets that have the specified tags |
Example:
const query = Stack.contentType('example').entries().tags(['technology', 'business']).find() query.then((result) => { // "result" contains list of entries which have tags "technology" and "business". }).catch((error) => { // Handle errors that occur during the query execution })
where
Pass JS expression or a full function to the query system. Evaluate js expressions
Name | Type | Description |
---|---|---|
field | string | UID of the field |
value (required) | string | Matches the entry field against this value |
Example:
const query = Stack.contentType('example').entries().where("this.title === 'Amazon_Echo_Black'").find() query.then((result) => { // ‘result’ contains the list of entries where value of ‘title’ is equal to ‘Amazon_Echo_Black’. }).catch(error) => { // Handle errors that occur during the query execution })