Is AI recommending you? Ask Contentstack Canoe for free
CS-log-dark.svg

TermQuery

View as Markdown

TermQuery

TermQuery lists the published terms of one taxonomy. Use it to read the term hierarchy of a taxonomy, in a locale and one page at a time.

TermQuery has no public constructor. The Terms method on a Taxonomy supplies the taxonomy UID below and returns a TermQuery:

NameTypeDescription
taxonomyUidstringUID of the taxonomy whose terms to list.

client.Taxonomies("<TAXONOMY_UID>").Terms() throws TaxonomyException (namespace Contentstack.Core.Internals) if the taxonomy has no UID. To read one term, use the Term method, which returns a Term.

AddParam

AddParam adds one query parameter to Find.

NameTypeDescription
key (required)string

Name of the query parameter, for example depth.

Default: Not applicable
value (required)string

Value of the query parameter.

Default: Not applicable

Returns: TermQuery. The same term query, for chaining.

Validation

  • Throws ArgumentNullException if key is null, because the SDK stores parameters in a dictionary keyed by name.
  • There is no other client-side validation. A null value sends the parameter with an empty value.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. AddParam stores the pair and makes no request. A second call with the same key replaces the first value, including a value from another modifier such as Limit.
  • Find sends the value.
  • Use it for a parameter that has no method on this class.

Example

Basic usage: send a parameter by name

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<JsonObject> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .AddParam("depth", "1")
        .Find<JsonObject>();
    foreach (JsonObject term in terms)
    {
        Console.WriteLine(term["uid"]);
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

Depth

Depth sets the depth of the term hierarchy that Find retrieves.

NameTypeDescription
depth (required)int

Number of hierarchy levels to retrieve.

Default: Not applicable

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation. Depth stores zero or a negative number as given.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. Depth stores the depth query parameter and makes no request. A second call replaces the first value.
  • Find sends the value (Get all terms).
  • Without Depth, the SDK sends no depth value and the API applies its own.

Example

Basic usage: list the terms two levels deep

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .Depth(2)
        .Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Uid}: {term.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Find

Find lists the published terms of the taxonomy.

Returns: Task<ContentstackCollection<T>>. The matching terms.

Validation

  • There is no client-side validation. The Terms method already rejected an instance without a taxonomy UID.
  • Throws TaxonomyException if the request fails, for example for an unknown taxonomy UID.
  • Throws TaxonomyException with ErrorCode 0 if a term in the response does not deserialize into T.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Calls GET /taxonomies/{taxonomy_uid}/terms (Get all terms) and makes one HTTP request per call.
  • Deserializes each item of the terms array of the response into T. Items on the result holds them, and the result is enumerable.
  • Sends every query parameter stored on the instance, from SetLocale, IncludeFallback, Depth, Skip, Limit, IncludeCount, IncludeBranch and AddParam.
  • Does not page automatically. Each call returns the one page of terms that the API sends back. Combine Skip and Limit to request the next page.
  • Count on the result holds a total only when the response carries count. Skip and Limit on the result stay 0, so track the page position in your own code.

Example

Basic usage: list the terms of a taxonomy

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>").Terms().Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Uid}: {term.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

Pagination: read every page of terms

using System;
using System.Linq;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    const int pageSize = 50;
    int skip = 0;
    while (true)
    {
        ContentstackCollection<JsonObject> page = await client.Taxonomies("<TAXONOMY_UID>")
            .Terms()
            .Skip(skip)
            .Limit(pageSize)
            .Find<JsonObject>();
        foreach (JsonObject term in page)
        {
            Console.WriteLine(term["uid"]);
        }

        // A short page is the last page
        if (page.Items.Count() < pageSize)
        {
            break;
        }
        skip += pageSize;
    }
}
catch (ContentstackException e)
{
    Console.WriteLine(e.Message);
}

IncludeBranch

IncludeBranch requests the branch information of each term by sending include_branch=true.

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. IncludeBranch stores include_branch=true and makes no request. No method removes it, so build a new instance to send a request without it.
  • Find sends the value.
  • Does not choose the branch. The Branch option on ContentstackOptions sets the branch the SDK reads from.

Example

Basic usage: list terms with their branch information

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<JsonObject> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .IncludeBranch()
        .Find<JsonObject>();
    foreach (JsonObject term in terms)
    {
        Console.WriteLine($"{term["uid"]}: {term["_branch"]}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

IncludeCount

IncludeCount requests the total number of terms by sending include_count=true.

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. IncludeCount stores include_count=true and makes no request. No method removes it, so build a new instance to send a request without it.
  • Find sends the value.
  • Count on the result of Find holds the total when the response carries count. Otherwise Count stays 0.

Example

Basic usage: read the total number of terms

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .IncludeCount()
        .Limit(10)
        .Find<TermInfo>();
    Console.WriteLine($"Total terms: {terms.Count}");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

IncludeFallback

IncludeFallback adds the terms that have no localization in the requested locale, through the locale fallback hierarchy of the branch.

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. IncludeFallback stores include_fallback=true and makes no request. No method removes it, so build a new instance to send a request without it.
  • Find sends the value.
  • The API also returns the terms that have no localization in the requested locale. Each term's locale field shows the locale it came from (Get all terms).
  • Works with or without SetLocale.
  • To use the fallback hierarchy of a branch other than main, set Branch on ContentstackOptions, so the SDK sends the branch header.

Example

Basic usage: list the terms in a locale, with fallback

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .SetLocale("<LOCALE>")
        .IncludeFallback()
        .Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Name} ({term.Locale})");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
    public string Locale { get; set; }
}

Limit

Limit caps the number of terms that Find returns.

NameTypeDescription
limit (required)int

Maximum number of terms to return.

Default: Not applicable

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation. Limit stores zero or a negative number as given.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. Limit stores the limit query parameter and makes no request. A second call replaces the first value.
  • Find sends the value (Get all terms).
  • Without Limit, the SDK sends no limit value and the API applies its own page size.
  • Combine it with Skip to page through the terms.

Example

Basic usage: return at most five terms

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .Limit(5)
        .Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Uid}: {term.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}

SetLocale

SetLocale sets the locale that Find returns the term names in.

NameTypeDescription
locale (required)string

Locale code, for example fr-fr.

Default: Not applicable

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation of the locale code.
  • A null or empty locale changes nothing. SetLocale keeps any locale set earlier and does not throw.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. SetLocale stores the locale query parameter and makes no request. A second call replaces the first value.
  • Find sends the value (Get all terms).
  • Without IncludeFallback, the API returns only the terms localized in this locale.
  • A locale set on the Taxonomy does not reach the term query. Set it on the TermQuery itself.

Example

Basic usage: list the terms in a locale

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .SetLocale("<LOCALE>")
        .Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Name} ({term.Locale})");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
    public string Locale { get; set; }
}

Skip

Skip skips a number of terms, so Find returns a later page.

NameTypeDescription
skip (required)int

Number of terms to skip.

Default: Not applicable

Returns: TermQuery. The same term query, for chaining.

Validation

  • There is no client-side validation. Skip stores a negative number as given.
  • An invalid value surfaces as a ContentstackException (or a subclass) when Find sends the request.

Additional Resource Refer to Content Delivery API Errors for the full error code list.

Behavior

  • Client-side only. Skip stores the skip query parameter and makes no request. A second call replaces the first value.
  • Find sends the value (Get all terms).
  • Combine it with Limit to page through the terms. The Find page shows a loop that reads every page.

Example

Basic usage: read the second page of 10 terms

using System;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    ContentstackCollection<TermInfo> terms = await client.Taxonomies("<TAXONOMY_UID>")
        .Terms()
        .Skip(10)
        .Limit(10)
        .Find<TermInfo>();
    foreach (TermInfo term in terms)
    {
        Console.WriteLine($"{term.Uid}: {term.Name}");
    }
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

public class TermInfo
{
    public string Uid { get; set; }
    public string Name { get; set; }
}