DataSync MongoDB SDK API Reference
The Contentstack DataSync MongoDB SDK enables developers to synchronize and query Contentstack data directly from a MongoDB database. This approach reduces API calls by serving content directly from local storage, optimizing delivery performance.
Additional Resource: To know more about DataSync MongoDB SDK, refer to the Get Started with DataSync MongoDB SDK documentation.
Stack
The Stack instance serves as the primary interface for interacting with your Contentstack data stored in MongoDB. It provides methods to query entries, assets, and content type schemas.
Example:
const Stack = Contentstack.Stack(config);
| Name | Type | Description |
|---|---|---|
dbName | string | Name of the MongoDB database. Defaults to 'contentstack-db'. |
uri | string | MongoDB connection URI. Defaults to 'mongodb://localhost:27017'. |
options | object | MongoDB connection options. Refer to MongoClient Options for details. |
Global
The Global class provides a rich set of methods that allows developers to build advanced queries on top of MongoDB-synced Contentstack data. These methods enable filtering, projection, sorting, reference handling, and more.
and
The and method combines multiple query conditions using a logical AND operator and returns entries that meet all the specified 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 |
|---|---|---|
field (required) | string | The field to sort in ascending order |
Example:
Stack
.contentType('example')
.entries()
.ascending('title')
.find()
.then((result) => {
// The result contains entries sorted in ascending order by the 'title' field
})
.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 to fetch; if not provided, returns the first asset found. |
Example:
Stack
.asset('uid')
.find()
.then((result) => {
// returns the asset based on its 'uid', if not provided, it would return the 1st asset found
})
.catch((error) => {
// Handle errors that occur during the query execution
})assets
The assets method retrieves a list of all assets.
Example:
Stack
.assets()
.find()
.then((result) => {
// Retrieves assets based on the query
})
.catch((error) => {
// Handle errors that occur during the query execution
})close
The close method closes the MongoDB connection.
Example:
Stack.close();
connect
The connect method establishes a connection to MongoDB with optional configuration overrides
| Name | Type | Description |
|---|---|---|
overrides (required) | object | Provides optional overrides or MongoDB-specific settings to customize query behavior. |
Example:
Stack
.connect(overrides)
.then((db) => {
// mongodb connection object indexes will be created on the collection in the background if provided in config
})
.catch((error) => {
// Handle errors that occur during the query execution
})containedIn
The containedIn method retrieves entries where the specified field's value matches any value in the provided array.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | array | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.containedIn('emails', ['[email protected]'])
.find()
.then((result) => {
// The result contains entries where the 'emails' field includes '[email protected]'
})
.catch((error) => {
// Handle errors that occur during the query execution
})contentType
The contentType method specifies the content type to query.
| Name | Type | Description |
|---|---|---|
uid (required) | string | UID of the content type to run the query against. |
Example:
Stack
.contentType('blog')
.entries()
.find()
.then((result) => {
// The result contains entries filtered by the 'blog' 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()
.then((result) => {
// returns a set of content type schemas
})
.catch((error) => {
// Handle errors that occur during the query execution
})count
The count method returns the total number of entries or assets that match the specified query.
| Name | Type | Description |
|---|---|---|
query | object | A filter object that defines conditions for the query. |
Example:
Stack
.contentType('blog')
.entries()
.count()
.find()
.then((result) => {
// returns entries count, without any of its assets or references
})
.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 |
|---|---|---|
field (required) | string | The field to sort in descending order |
Example:
Stack
.contentType('example')
.entries()
.descending('title')
.find()
.then((result) => {
// result sorted in descending manner with respect to 'title' field
})
.catch((error) => {
// Handle errors that occur during the query execution
})entries
The entries method initiates a query for a set of entries within the specified content type.
| Name | Type | Description |
|---|---|---|
uid | string | UID of the entry to fetch; if not provided, returns the first entry found. |
Example:
Stack
.contentType('blog')
.entries()
.find()
.then((result) => {
// The result contains entries filtered by the 'blog' content type
})
.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 | UID of the entry to fetch; if not provided, returns the first entry found. |
Example:
Stack
.contentType('blog')
.entry('uid')
.find()
.then((result) => {
// returns the entry based on its 'uid', if not provided, it would return the 1st entry found in 'blog' content type
})
.catch((error) => {
// handle query errors
})except
The except method excludes the specified fields from the response.
| Name | Type | Description |
|---|---|---|
fields | array | Array of field UIDs, using dot notation for querying embedded documents |
Example:
Stack
.contentType('blog')
.entries()
.except(['title', 'url', 'links'])
.find()
.then((result) => {
// returns entries and projects all of their properties, except - ["title", "url", "links"]
})
.catch((error) => {
// Handle errors that occur during the query execution
})excludeReferences
The excludeReferences method excludes all references of the entries being returned.
Note: On calling this, referenced entries and assets will not be included in the result.
Example:
Stack
.contentType('blog')
.entries()
.excludeReferences()
.find()
.then((result) => {
// returns entries, without any of its assets or references
})
.catch((error) => {
// Handle errors that occur during the query execution
})exists
The exists method filters entries that contain the specified field.
| Name | Type | Description |
|---|---|---|
key (required) | string | Field to check existence for |
Example:
Stack
.contentType('blog')
.entries()
.exists('emails')
.find()
.then((result) => {
// The result contains entries where the 'emails' property exists
})
.catch((error) => {
// Handle errors that occur during the query execution
})fetch
The fetch method executes a query using the provided query object. It returns a single entry/asset/content type object after applying all filters and references.
| Name | Type | Description |
|---|---|---|
query | object | Query object that overrides all previous query filters |
Example:
Stack
.contentType('blog')
.entries()
.fetch()
.then((result) => {
// returns a 'blog' content type's entries
})
.catch((error) => {
// Handle errors that occur during the query execution
})find
The find method processes and executes all built queries, and returns the matching result.
| Name | Type | Description |
|---|---|---|
query | object | Query object that overrides all previous query filters |
Example:
Stack
.contentType('blog')
.entries()
.find()
.then((result) => {
// returns 'blog' content type's entries
})
.catch((error) => {
// Handle errors that occur during the query execution
})findOne
Note: This method is deprecated. Use fetch instead.
The findOne method executes a query using the provided query object. It returns a single entry/asset/content type object after applying all filters and references.
| Name | Type | Description |
|---|---|---|
query | object | Query object that overrides all previous query filters |
Example:
Stack
.contentType('blog')
.entries()
.findOne()
.then((result) => {
// returns 'blog' content type's entries
})
.catch((error) => {
// Handle errors that occur during the query execution
})getQuery
The getQuery method exposes the query object built using chained query methods.
Example:
const query = Stack
.contentType('blog')
.entries()
.getQuery();
// exposes details of the queries formed inside the SDKgreaterThan
The greaterThan method retrieves entries where the specified field’s value is greater than the provided value.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.greaterThan('age', 60)
.find()
.then((result) => {
// Retrieves entries where age is greater than 60
})
.catch((error) => {
// Handle errors that occur during the query execution
})greaterThanOrEqualTo
The greaterThanOrEqualTo method retrieves entries where the specified field’s value is greater than or equal to the provided value.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.greaterThanOrEqualTo('age', 60)
.find()
.then((result) => {
// Retrieves entries where age is greater than or equal to 60
})
.catch((error) => {
// Handle errors that occur during the query execution
})include
The include method includes specific reference fields in the response.
| Name | Type | Description |
|---|---|---|
fields (required) | object | An array of reference field UIDs to include |
Example:
Stack
.contentType('blog')
.entries()
.include(['related_blogs', 'authors.blogs']) // here related_blogs and authors.blogs are reference field uids
.find()includeContentType
The includeContentType method includes the content type schema of the entries in the response.
Example:
Stack
.contentType('blog')
.entries()
.includeContentType()
.find()
.then((result) => {
// returns entries, along with a 'content_type' property, which is 'blog' content type's schema
})
.catch((error) => {
// Handle errors that occur during the query execution
})includeCount
The includeCount method includes the total count of matching entries in the result response.
Example:
Stack
.contentType('blog')
.entries()
.includeCount()
.find()
.then((result) => {
// returns entries, along with a 'count' property, with the total count of entries being returned
})
.catch((error) => {
// Handle errors that occur during the query execution
})includeReferences
The includeReferences method includes all the references of your queried entries (default depth 2).
Note: To increase the depth of the references fetched, call .referenceDepth(number).
Example:
Stack
.contentType('blog')
.entries()
.includeReferences()
.find()language
The language method sets the locale to be used when querying entries.
| Name | Type | Description |
|---|---|---|
code (required) | string | Language code to use |
Example:
Stack
.contentType('blog')
.entries()
.language('es-es')
.find()
.then((result) => {
// returns entries fetched from 'es-es' locale
})
.catch((error) => {
// Handle errors that occur during the query execution
})lessThan
The lessThan method retrieves entries where the value of a specified field is less than the provided value.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.lessThan('age', 25)
.find()
.then((result) => {
// Retrieves entries where age is less than 25
})
.catch((error) => {
// Handle errors that occur during the query execution
})lessThanOrEqualTo
The lessThanOrEqualTo method retrieves entries where the specified field’s value is less than or equal to the given value.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.lessThanOrEqualTo('age', 25)
.find()
.then((result) => {
// Retrieves entries where age is less than or equal to 25
})
.catch((error) => {
// Handle errors that occur during the query execution
})limit
The limit method restricts the number of entries returned by the query.
| Name | Type | Description |
|---|---|---|
limit (required) | number | Maximum number of results to return |
Example:
Stack
.contentType('example')
.entries()
.limit(5)
.find()
.then((result) => {
// returns top 5 entries of 'example' content type
})
.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 value in the given array.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | Array of values to exclude |
Example:
Stack
.contentType('example')
.entries()
.notContainedIn('emails', ['[email protected]'])
.find()
.then((result) => {
// The result contains entries where the 'emails' property does not include '[email protected]'
})
.catch((error) => {
// Handle errors that occur during the query execution
})notEqualTo
The notEqualTo method retrieves entries where the specified field’s value does not equal the given value.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to compare values against in the query. |
value (required) | any | The value or values to compare against the field. |
Example:
Stack
.contentType('example')
.entries()
.notEqualTo('title', 'Demo')
.find()
.then((result) => {
// Retrieves entries where 'title' is not equal to 'Demo'
})
.catch((error) => {
// Handle errors that occur during the query execution
})notExists
The notExists method filters entries that do not contain the specified field.
| Name | Type | Description |
|---|---|---|
key (required) | string | The field to check for absence in the entry. |
Example:
Stack
.contentType('blog')
.entries()
.notExists('emails')
.find()
.then((result) => {
// The result contains entries where the 'emails' property does not exist.
})
.catch((error) => {
// Handle errors that occur during the query execution
})
only
The only method includes only the specified fields in the result set.
| Name | Type | Description |
|---|---|---|
fields (required) | array | Array of field UIDs to be included (dot notation supported) |
Example:
Stack
.contentType('blog')
.entries()
.only(['title', 'url', 'links'])
.find()
.then((result) => {
// Returns entries with only the 'title', 'url', and 'links' fields
})
.catch((error) => {
// Handle errors that occur during the query execution
})
or
The or method combines multiple conditions using the logical OR operator and returns entries that match at least one of the conditions.
| Name | Type | Description |
|---|---|---|
queries (required) | array | Array of query condition objects |
Example:
Stack
.contentType('example')
.entries()
.or([{ title: 'John' }, { title: 'Jane' }])
.find()
.then((result) => {
// Retrieves entries where title is "John" or "Jane"
})
.catch((error) => {
// Handle errors that occur during the query execution
})query
The query method initializes a query builder with the specified raw MongoDB query.
| Name | Type | Description |
|---|---|---|
userQuery (required) | object | Raw MongoDB query object |
Example:
Stack
.contentType('example')
.entries()
.query({ "authors.name": "John Doe" })
.find()
.then((result) => {
// returns entries, whose reference authors.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 reference fields that are included using .includeReferences().
| Name | Type | Description |
|---|---|---|
query (required) | object | Query filter for referenced entries |
Example:
Stack
.contentType('blog')
.entries()
.includeReferences() // Includes all references of the content type
.queryReferences({ "authors.name": "John Doe" })
.find()referenceDepth
The referenceDepth method overrides the default reference resolution depth of 2 when using .includeReferences().
| Name | Type | Description |
|---|---|---|
depth (required) | number | Desired nested reference depth |
Example:
Stack
.contentType('blog')
.entries()
.includeReferences()
.referenceDepth(4)
.find()regex
The regex method retrieves entries where the value of the specified field matches the given regular expression.
| Name | Type | Description |
|---|---|---|
key (required) | string | The unique identifier of the field to match in the query |
value (required) | string | The regex pattern to test against the field's value. |
options | string | Regex options to apply (e.g., 'i' for case-insensitive). |
Example:
Stack
.contentType('example')
.entries()
.regex('title', '^Demo')
.find()
// or with options
Stack
.contentType('example')
.entries()
.regex('title', '^Demo', 'i')
.find()schema
The schema method fetches the schema definition for the specified content type.
| Name | Type | Description |
|---|---|---|
uid | string | UID of the content type |
Example:
Stack
.schema('blog')
.find()schemas
The schemas method fetches all content type schemas.
Example:
Stack .schemas() .find()
skip
The skip method skips the specified number of entries from the start of the result set.
| Name | Type | Description |
|---|---|---|
value (required) | number | Number of entries to skip |
Example:
Stack
.contentType('example')
.entries()
.skip(10)
.find()
.then((result) => {
// skips the first 10 entries, returns the rest
})
.catch((error) => {
// Handle errors that occur during the query execution
})tags
The tags method filters entries/assets that include the specified tags.
| Name | Type | Description |
|---|---|---|
tags (required) | array | An array of tags to match |
Example:
Stack
.contentType('example')
.entries()
.tags(['tag1', 'tag2'])
.find()
.then((result) => {
// returns entries which have tags "tag1" and "tag2"
})
.catch((error) => {
// Handle errors that occur during the query execution
})where
The where method applies a custom JavaScript expression to evaluate and filter entries.
| Name | Type | Description |
|---|---|---|
filter (required) | string | JavaScript expression as a string |
Example:
Stack
.contentType('example')
.entries()
.where("this.title === 'Amazon_Echo_Black'")
.find()
.then((result) => {
// returns entries where title matches the expression
})
.catch((error) => {
// Handle errors that occur during the query execution
})