Preview GraphQL API limitations and restrictions

Custom field naming

Custom field names used in search predicates cannot start with an underscore (_). The search service reserves the underscore prefix for system fields, such as _name, _path, _language, and so on. If you attempt to search on a custom field named _myCustomField, an exception occurs (NotSupportedFieldException) because the service attempts to resolve the custom field against the internal allowlist of system fields.

Pagination limits

Pagination limits differ based on the query type:

• allSiteInfo query - the combination of offset (pageNumber × pageSize) cannot exceed 10,000. When this number is exceeded, the following error message displays:

  Offset paging only supports up to 10000 sites but was {X}

• Dictionary query - the first argument (page size) on the site node cannot exceed 1,000. Requesting first 1,001 or greater on fields, such as site { siteInfo { dictionary(first: 1001) } }, results in a GraphQL error:

  The 'first' value should not be greater than 1000

Operator behavior

The Equality operator (EQ) behaves like the Contains operator for string fields. For example, the following search predicate does not result in an exact match due to field tokenization. To work around this limitation, see the related support article KB1003665.

name: "customField"
value: "value to look for"
operator: EQ

Ordering behavior

A search query might return inconsistent results when using orderBy with item text fields due to field tokenization.

Route path limits

The routes field on the site query restricts the number of filtered paths. The sum of strings provided to includedPaths and excludedPaths arguments must not exceed 100. Exceeding this limit results in an error:

In the 'routes' field, the total number of 'excludedPaths' and 'includedPaths' cannot be more than 100

URL resolution

The url field on items is resolved using overridden ItemUrlBuilderOptions:

• AlwaysIncludeServerUrl is set to true.
• AlwaysExcludeVirtualFolder is set to true.
• SiteResolving is disabled (false).
• Spaces are encoded into dashes.