Taxonomy

Taxonomy helps you categorize pieces of content within your stack to facilitate easy navigation, search, and retrieval of information.

NoteAll methods in the Query section are applicable for taxonomy-based filtering as well.

equalAndBelow

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

Example:

const data = await stack
                   .taxonomy()
                   .where(
                       'taxonomies.one',
                       TaxonomyQueryOperation.EQ_BELOW,
                       'term_one',
                       {"levels": 1}  // optional
                   )
                   .find<TEntries>()

below

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

Example:

const data = await stack

                   .taxonomy()

                   .where(

                       'taxonomies.one',

                       TaxonomyQueryOperation.BELOW,

                       'term_one',

                       {"levels": 1}  // optional

                   )

                   .find<TEntries>()

equalAndAbove

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

Example:

const data = await stack

                   .taxonomy()

                   .where(

                       'taxonomies.one',

                       TaxonomyQueryOperation.EQ_ABOVE,

                       'term_one',

                       {"levels": 1}  // optional

                   )

                   .find<TEntries>()

above

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

Example:

const data = await stack

                   .taxonomy()

                   .where(

                       'taxonomies.one',

                       TaxonomyQueryOperation.ABOVE,

                       'term_one',

                       {"levels": 1}  // optional

                   )

                   .find<TEntries>()

fetch

The fetch method retrieves the details of a specific published taxonomy by UID.

Name	Type	Description
locale	string	Locale code (for example, hi-in), passed positionally. Omit to retrieve the master locale. Default: master locale

Validation

locale is an optional positional argument, not a chained setter. It must be passed directly to fetch(locale). There is no client-side validation of the locale code. An invalid or unpublished locale is rejected by the API. See Delivery API Errors.

Behavior

Maps to a single GET request to /taxonomies/{taxonomy_uid}. The response is unwrapped from response.taxonomy. If that key is absent, the raw response is returned as-is.

Example

import contentstack, {BaseTaxonomy} from '@contentstack/delivery-sdk'


interface BlogTaxonomy extends BaseTaxonomy {

  uid: string

  name: string

}


const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" })


// Master locale

const result = await stack

    .taxonomy(taxonomy_uid)

    .fetch<BlogTaxonomy>()


// Localized

const localized = await stack

    .taxonomy(taxonomy_uid)

    .fetch<BlogTaxonomy>('hi-in')

term

The term method returns either a Term instance or a TermQuery instance, depending on whether a term UID is passed. Pass a UID to fetch a single term. Omit the UID to build a query across all terms in the taxonomy.

Name	Type	Description
uid	string	UID of the term. When passed, returns a Term. When omitted, returns a TermQuery. Default: none

Instance State

The TypeScript SDK exposes a single overloaded term() method for both call shapes. This differs from the .NET SDK, which splits the same behavior into two separate methods, Term(termUid) and Terms(). Calling term('term_uid') in TypeScript is equivalent to Term(termUid) in .NET. Calling term() with no argument is equivalent to Terms() in .NET.

Validation

There is no client-side validation of uid. An empty string is treated the same as an omitted argument because the method checks if (uid), so passing term('') returns a TermQuery, not a Term. An invalid or nonexistent term UID does not throw at this step. The API rejects it on the subsequent fetch() call. See Delivery API Errors.

Behavior

Client-side only. Constructs a Term or TermQuery instance. No HTTP call is made until a terminal method (fetch(), locales(), ancestors(), descendants(), or find()) is called on the returned object.

Example

import contentstack from '@contentstack/delivery-sdk'


const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" })


// Get a specific term (returns a Term)

const term = stack.taxonomy('taxonomy_uid').term('term_uid')


// Get all terms (returns a TermQuery)

const termQuery = stack.taxonomy('taxonomy_uid').term()