Global Fields

addParams merges several query parameters into the request that find sends.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. addParams merges any key and value, and an empty object changes nothing.
• Passing a value that is not a string, boolean, or number, such as an array, is a compile error.
• Errors surface on the find() call that follows, not on addParams(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. addParams merges the object into the query parameters, and find sends them.
• addParams overwrites a key that already exists. Keys you do not pass stay as they are.
• Unlike the param method, addParams accepts boolean values. The request sends them as true or false.
• Known issue: In 5.x, includeBranch does not compile after addParams, because TypeScript types the return value as Query. Call the includeBranch method before addParams, as Chain order on the Global Fields class page describes.

Example

Basic usage: set several parameters at once

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().addParams({ include_count: true, limit: 5 }).find();
  console.log('returned', result.global_fields?.length, 'of', result.count);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: merging keeps the keys you do not pass

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // limit comes from addParams, skip from the earlier call stays.
  const result = await stack.globalField().skip(1).addParams({ limit: 3 }).find();
  console.log('returned', result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}

fetch retrieves the schema and details of one global field by its UID.

Returns: Promise<T>. The requested global field.

Validation

• There is no client-side validation. fetch sends whatever global field UID the object holds.
• fetch exists only on GlobalField. Calling it on stack.globalField() without a UID is a compile error.
• fetch throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message. An unknown global field UID throws status 422 with error_code 118. A network failure throws status 0, with the Node.js error code, such as ENOTFOUND, in error_code.

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

Behavior

• One call sends one GET /global_fields/{global_field_uid} request, with the include_branch parameter when you chained the includeBranch method.
• fetch returns the value of the response's global_field key, not the whole body. Any other top-level key does not reach your code.
• fetch is generic. Pass your own interface as T to type the result. The SDK exports no global field type and does not check the response against T.
• Calling fetch again on the same object sends the same request again.

Example

Basic usage: read one global field by UID

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField('<GLOBAL_FIELD_UID>').fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Typed result: list the fields inside the global field

import contentstack from '@contentstack/delivery-sdk';

interface SeoGlobalField {
  uid: string;
  title: string;
  schema: { uid: string; data_type: string; display_name: string }[];
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const globalField = await stack.globalField('<GLOBAL_FIELD_UID>').includeBranch().fetch<SeoGlobalField>();
  for (const field of globalField.schema) {
    console.log(field.uid, field.data_type, field.display_name);
  }
} catch (error: any) {
  console.error(error);
}

Error handling: an unknown global field UID

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  await stack.globalField('no_such_global_field').fetch();
} catch (error: any) {
  // The API rejects a global field UID that does not exist with status 422 and error_code 118.
  if (error.status === 422) {
    console.error('No global field with that UID:', error.status, error.error_message);
  } else {
    console.error(error);
  }
}

find retrieves the global fields of the stack, with the parameters the query holds.

Returns: Promise<FindResponse<T>>. The matching global fields.

Validation

• There is no client-side validation. find sends whatever parameters the query holds.
• find exists only on GlobalFieldQuery. Calling it on stack.globalField('<GLOBAL_FIELD_UID>') is a compile error.
• find throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message. A network failure throws status 0, with the Node.js error code, such as ENOTFOUND, in error_code.

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

Behavior

• One call sends one GET /global_fields request and returns one page. The SDK does not iterate pages.
• find returns the response body unchanged, and TypeScript types it as FindResponse<T>. The list is under global_fields, which TypeScript types as T[], and count is present when you chained the includeCount method.
• encode has no effect on this class. It encodes the query filter object, and GlobalFieldQuery has no filter methods that fill it.
• Calling find again on the same object sends the same parameters again.

Example

Basic usage: list the global fields of the stack

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().find();
  console.log(result.global_fields?.length, 'global fields');
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

All parameters: pass encode and type the list

import contentstack from '@contentstack/delivery-sdk';

interface GlobalFieldSchema {
  uid: string;
  title: string;
  schema: unknown[];
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // encode has no effect here, because GlobalFieldQuery builds no query filter.
  const result = await stack.globalField().includeCount().find<GlobalFieldSchema>(true);
  for (const globalField of result.global_fields ?? []) {
    console.log(globalField.uid, globalField.title, globalField.schema.length, 'fields');
  }
  console.log('total:', result.count);
} catch (error: any) {
  console.error(error);
}

Edge case: filter the list in your own code

import contentstack from '@contentstack/delivery-sdk';

interface GlobalFieldSchema {
  uid: string;
  title: string;
  schema: { uid: string; data_type: string }[];
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // GlobalFieldQuery has no where(), so filter after find returns.
  const result = await stack.globalField().find<GlobalFieldSchema>();
  const withFiles = (result.global_fields ?? []).filter((globalField) =>
    globalField.schema.some((field) => field.data_type === 'file'),
  );
  console.log('global fields with a file field:', withFiles.map((globalField) => globalField.uid));
} catch (error: any) {
  console.error(error);
}

includeBranch asks the API to include the _branch key, which names the branch that the global field belongs to.

Returns: GlobalField or GlobalFieldQuery. The same object, for chaining.

Validation

• There is no client-side validation. includeBranch takes no input.
• Known issue: In 5.x, on GlobalFieldQuery, calling includeBranch after a method such as limit is a compile error, because TypeScript types that method as returning Query. Call includeBranch first, as Chain order on the Global Fields class page describes.
• Errors surface on the fetch() or find() call that follows, not on includeBranch(). That call throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. includeBranch sets the include_branch query parameter to 'true', and the fetch or find that follows sends it.
• The API puts _branch inside each global field object, not at the top level of the response. The result of fetch, and each item in the global_fields array of find, carries it.
• includeBranch exists on both objects and returns the object you called it on.
  • On stack.globalField('<GLOBAL_FIELD_UID>'), it returns the same GlobalField, ready for fetch.
  • On stack.globalField(), it returns the same GlobalFieldQuery, and TypeScript keeps that type, so every method of the class stays available after it.
• Calling it twice changes nothing. On GlobalFieldQuery, call the removeParam method with 'include_branch' to drop the flag. GlobalField has no remover.
• includeBranch changes the response only. To read content from another branch, set branch when you create the stack.

Example

Basic usage: read one global field with its branch

import contentstack from '@contentstack/delivery-sdk';

interface GlobalFieldWithBranch {
  uid: string;
  title: string;
  _branch?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField('<GLOBAL_FIELD_UID>').includeBranch().fetch<GlobalFieldWithBranch>();
  console.log(result.uid, 'branch:', result._branch);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

No UID: list global fields with their branch

import contentstack from '@contentstack/delivery-sdk';

interface GlobalFieldWithBranch {
  uid: string;
  title: string;
  _branch?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // includeBranch first, because limit returns the Query type.
  const result = await stack.globalField().includeBranch().limit(10).find<GlobalFieldWithBranch>();
  for (const globalField of result.global_fields ?? []) {
    console.log(globalField.uid, globalField._branch);
  }
} catch (error: any) {
  console.error(error);
}

includeCount adds the total number of global fields in the stack to the response, as count.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. includeCount takes no input.
• Errors surface on the find() call that follows, not on includeCount(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. includeCount sets the include_count query parameter to 'true', and find sends it.
• The response then carries count, the total number of global fields. It can exceed the number of global fields on one page.
• Calling it twice changes nothing. Call the removeParam method with 'include_count' to drop the flag.
• Known issue: In 5.x, includeBranch does not compile after includeCount, because TypeScript types the return value as Query. Call the includeBranch method before includeCount, as Chain order on the Global Fields class page describes.

Example

Basic usage: count the global fields in the stack

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().includeCount().find();
  console.log('total global fields:', result.count);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Pagination: find out whether more global fields remain

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().limit(2).includeCount().find();
  const returned = result.global_fields?.length ?? 0;
  console.log('returned', returned, 'of', result.count, 'more remain:', returned < (result.count ?? 0));
} catch (error: any) {
  console.error(error);
}

limit caps the number of global fields the response contains.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. limit stores zero, a negative number, or a fraction as given. The API ignores a limit of 0 or less and applies its default page size.
• Passing a string, such as limit('5'), is a compile error.
• Errors surface on the find() call that follows, not on limit(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. limit sets the limit query parameter, and find sends it.
• Omitting limit does not return every global field. The API applies its own page size. See Pagination on the Global Fields class page.
• A second call replaces the first value, because the query holds one limit value.
• Known issue: In 5.x, includeBranch does not compile after limit, because TypeScript types the return value as Query. Call the includeBranch method before limit, as Chain order on the Global Fields class page describes.

Example

Basic usage: return at most five global fields

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().limit(5).find();
  console.log('returned', result.global_fields?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Pagination: read every global field one page at a time

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

const pageSize = 10;
const all: unknown[] = [];

try {
  let skip = 0;
  let total = 0;
  do {
    // A fresh query per page, so each request carries its own skip value.
    const page = await stack.globalField().skip(skip).limit(pageSize).includeCount().find();
    const items = page.global_fields ?? [];
    all.push(...items);
    total = page.count ?? 0;
    skip += pageSize;
    if (items.length === 0) break;
  } while (skip < total);
  console.log('read', all.length, 'of', total, 'global fields');
} catch (error: any) {
  console.error(error);
}

orderByAscending sorts the global fields in ascending order of one field.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. orderByAscending stores an empty string or an unknown field UID as given.
• Calling orderByAscending without an argument is a compile error.
• Errors surface on the find() call that follows, not on orderByAscending(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. orderByAscending sets the asc query parameter to the field UID, and find sends it.
• A second call replaces the field, because the query holds one asc value.
• orderByAscending and the orderByDescending method write different keys, so calling both sends asc and desc together. Call the removeParam method with 'desc' to keep one sort.
• Known issue: In 5.x, includeBranch does not compile after orderByAscending, because TypeScript types the return value as Query. Call the includeBranch method before orderByAscending, as Chain order on the Global Fields class page describes.

Example

Basic usage: sort global fields by title

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().orderByAscending('title').find();
  console.log(result.global_fields?.length, 'global fields sorted by title');
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: switch the sort direction on an existing query

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

// The query starts with the opposite sort.
const query = stack.globalField().orderByDescending('created_at');

try {
  // Drop the old key, then set the new one, so the request carries one sort.
  const result = await query.removeParam('desc').orderByAscending('title').find();
  console.log(result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}

orderByDescending sorts the global fields in descending order of one field.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. orderByDescending stores an empty string or an unknown field UID as given.
• Calling orderByDescending without an argument is a compile error.
• Errors surface on the find() call that follows, not on orderByDescending(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. orderByDescending sets the desc query parameter to the field UID, and find sends it.
• A second call replaces the field, because the query holds one desc value.
• orderByDescending and the orderByAscending method write different keys, so calling both sends asc and desc together. Call the removeParam method with 'asc' to keep one sort.
• Known issue: In 5.x, includeBranch does not compile after orderByDescending, because TypeScript types the return value as Query. Call the includeBranch method before orderByDescending, as Chain order on the Global Fields class page describes.

Example

Basic usage: sort global fields by updated_at

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().orderByDescending('updated_at').find();
  console.log(result.global_fields?.length, 'global fields sorted by updated_at');
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: switch the sort direction on an existing query

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

// The query starts with the opposite sort.
const query = stack.globalField().orderByAscending('created_at');

try {
  // Drop the old key, then set the new one, so the request carries one sort.
  const result = await query.removeParam('asc').orderByDescending('updated_at').find();
  console.log(result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}

param sets one query parameter on the request that find sends.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. param stores any key, including one the API does not recognize, and any value, including an empty string.
• Passing a boolean value, such as param('include_count', true), is a compile error. Pass the string 'true', or use the addParams method, which accepts booleans.
• Errors surface on the find() call that follows, not on param(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. param writes the key and value into the query parameters, and find sends them.
• param replaces a key that another method already set. For example, param('limit', 5) replaces a value from the limit method.
• Use param for an API parameter that GlobalFieldQuery has no method for.
• Known issue: In 5.x, includeBranch does not compile after param, because TypeScript types the return value as Query. Call the includeBranch method before param, as Chain order on the Global Fields class page describes.

Example

Basic usage: set a parameter the class has no method for

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().param('include_branch', 'true').find();
  console.log(result.global_fields?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: a later call replaces an earlier value

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // The second value replaces the first, so the request carries limit=2.
  const result = await stack.globalField().limit(10).param('limit', 2).find();
  console.log('returned', result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}

removeParam deletes one query parameter from the request that find sends.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. A key the query does not hold changes nothing.
• Calling removeParam without an argument is a compile error.
• Errors surface on the find() call that follows, not on removeParam(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. removeParam deletes the key from the query parameters, so the next find omits it.
• It removes keys that any method set, for example include_count from the includeCount method or limit from the limit method.
• It cannot remove environment or the stack-level locale. The stack sends those on every request, and they never enter the query parameters.
• Known issue: In 5.x, includeBranch does not compile after removeParam, because TypeScript types the return value as Query. Call the includeBranch method before removeParam, as Chain order on the Global Fields class page describes.

Example

Basic usage: drop a flag before the next request

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

const query = stack.globalField().includeCount();

try {
  // The request no longer asks for the total count.
  const result = await query.removeParam('include_count').find();
  console.log('count present:', result.count !== undefined);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: stack-level parameters stay

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // environment comes from the stack, so this call changes nothing.
  const result = await stack.globalField().removeParam('environment').find();
  console.log(result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}

skip leaves out a number of global fields from the start of the list, for pagination.

Returns: GlobalFieldQuery. The same query, for chaining.

Validation

• There is no client-side validation. skip stores a negative number or a fraction as given. The API treats a negative skip as 0.
• Passing a string, such as skip('10'), is a compile error.
• Errors surface on the find() call that follows, not on skip(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. skip sets the skip query parameter, and find sends it.
• Combine skip with the limit method to read one page at a time.
• A skip value at or past the total returns an empty global_fields array, not an error.
• A second call replaces the first value, because the query holds one skip value.
• Known issue: In 5.x, includeBranch does not compile after skip, because TypeScript types the return value as Query. Call the includeBranch method before skip, as Chain order on the Global Fields class page describes.

Example

Basic usage: read the second page of ten global fields

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.globalField().orderByAscending('created_at').skip(10).limit(10).find();
  console.log('second page:', result.global_fields?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: skip past the last item

import contentstack from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const counted = await stack.globalField().limit(1).includeCount().find();
  const total = counted.count ?? 0;

  // Skipping every global field returns an empty array, not an error.
  const result = await stack.globalField().skip(total).find();
  console.log('past the end:', result.global_fields?.length);
} catch (error: any) {
  console.error(error);
}