Customize GraphQL Queries in Commerce React Components

Info: This feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for details.

Overview

Starting with version 14.7.1, Commerce React Components support customization of internal GraphQL queries and variables. When you use a custom hook from a Commerce React Component, you can provide an optional CustomQueryOptionsProcessor implementation in the input properties. If present, the component invokes your processor to modify the internal GraphQL query and variables before executing the request. If your processor returns updated values, the component uses those instead of the defaults.

CustomQueryOptionsProcessor Interface

From v14.7.1 onward, most Commerce React Components accept an optional CustomQueryOptionsProcessor object in their input properties:

/**
 * Interface for the input and the output of the [[`CustomQueryOptionsProcessor`]]
 * which can be supplied by the application code in order to customize the original
 * GraphQL query document and query options object including variables inside this interface.
 * @category CustomQueryOptionsProcessor
 */
export interface CustomQueryOptions<TData = any, TVariables = OperationVariables> {
  query: DocumentNode | TypedDocumentNode<TData, TVariables | OperationVariables>;
  options?: QueryHookOptions<TData, TVariables | OperationVariables>;
}

/**
 * The interface to process the original GraphQL query document and query options object
 * while using the [[`useQueryCustom`]] hook function.
 * @category CustomQueryOptionsProcessor
 */
export interface CustomQueryOptionsProcessor<TData, TVariables = OperationVariables> {
  /**
   * Process the original GraphQL query document and query options object to affect the default internal
   * query execution
   * @param customQueryOptions the original GraphQL query document and query options
   * @returns a processed GraphQL query document and query options if updated; or null if no update necessary
   */
  process(customQueryOptions: CustomQueryOptions<TData, TVariables>): CustomQueryOptions;
}
copy

For example, the useProductGridSearch hook accepts input properties that include an optional customQueryOptionsProcessor property. The generic types TData and TVariables are set to Items and ItemsVariables for product search:

/**
 * @category Product
 */
export interface ProductGridSearchInputProps extends CommonProductInputProps {
  /**
   * Initial keyword to search products by.
   */
  searchText?: string;

  // ...

  /**
   * Optional Custom Query and Options Processor to update the original query document and variables if necessary
   */
  customQueryOptionsProcessor?: CustomQueryOptionsProcessor<Items, ItemsVariables>;
}

// ...

export function useProductGridSearch({
  searchText,
  // ...
  customQueryOptionsProcessor,
}: ProductGridSearchInputProps): [
  (offset?: number) => Promise<void>,
  ItemsResponse | undefined,
  boolean,
  ApolloError | undefined,
] {
  // ...
}
copy

When you provide a customQueryOptionsProcessor, the component follows this process:

• The component creates a CustomQueryOptions object containing the internal GraphQL query document (query) and query options with variables (options).
• The customQueryOptionsProcessor receives this object and can inspect or modify the query and variables.
• If no changes are needed, return the input object unchanged.
• If you need to customize the query or variables, return a new CustomQueryOptions object with the desired updates.
• The component uses the returned query and variables for the GraphQL request.

By implementing and supplying a CustomQueryOptionsProcessor, you can override the internal GraphQL query or variables as needed for your application.

Example

To customize the GraphQL query when using the useCategory hook (which retrieves a commerce category), follow these steps.

The default usage queries a category by ID:

const [category, loading, catError] = useCategory({ categoryId });
copy

To optimize the query by selecting fewer fields and adding a new variable, implement a custom processor:

//...
import { gql } from '@apollo/client';
//...

  // Define a custom GraphQL query document
  const myNewQuery = gql`
    query Category($id: String!, $queryHint: QueryHintInput) {
      findCategoryById(id: $id, queryHint: $queryHint) {
        id
        displayName
        slug
      }
    }
  `;

  // Implement a CustomQueryOptionsProcessor to override the query and add a variable
  const customQueryOptionsProcessor = {
    process: (customQueryOptions: CustomQueryOptions<Category | CategoryBySlug, CategoryVariables | CategoryBySlugVariables>) => {
      // Access the original query and variables
      const originalQuery = customQueryOptions.query;
      const originalVars = customQueryOptions.options?.variables ?? {} as CategoryVariables | CategoryBySlugVariables;
      // Append a new variable without removing existing ones
      const newVars = {...originalVars, newVar: 'newValue' };
      // Return the updated query and variables
      return { query: newQuery, options: { ...customQueryOptions.options, ...{ variables: newVars } } };
    },
  };
copy

Important:
Always append new variables to the existing options.variables object. Do not replace the entire variables object. Many Commerce React Components rely on existing variables and option parameters for backend-specific features or optimizations (such as the queryHint variable for data fetching). Replacing the variables object may break these features.