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.

NameTypeDescription
baseDirstring

Base directory of the folder where data is stored

localestring

Default locale to use when .language() is not specified in a query

referenceDepthnumber

The default nested reference field depth considered when calling .includeReferences(). This can be overridden by passing a numerical argument to .includeReferences(n)

projectionsobject

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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
queryobject

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.

NameTypeDescription
queryobject

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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
depthnumber

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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
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.

NameTypeDescription
key (required)string

Field UID to filter

value (required)Any[]

An array of values to match against

optionsstring

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.

NameTypeDescription
uidstring

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.

NameTypeDescription
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.

NameTypeDescription
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

NameTypeDescription
fieldstring

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
})