Documentation Center

Search commerce products

Use the externalItems GraphQL query search for and retrieve Magento Commerce product data based on matching search text.

Query syntax

The following code illustrates required format for the GraphQL request, followed by a description of the input values:

{
   externalItems([namespace: "NAMESPACE"]
            filter: {
              [context: {
                [namespace: "NAMESPACE",]
                id: "IDENTIFIER",
                type: "TYPE"
              },]
              [searchText: "SEARCH TEXT",]
              [type: "TYPE"]
            },
            # Pagination
            [first: NUM_ITEMS,]
            [after: "[cursor]"]) 
   {
       edges {
         node {
            ... on TYPE {
            RESPONSE_FIELD_1
            RESPONSE_FIELD_2
            RESPONSE_FIELD_n
            }
         }
      }
   }
}

Fields and inputs

namespace
Sets the overall query scope, where NAMESPACE is the namespace name for query.
If used in the context identity, the namespace does not need to be separately specified here.
filter
Defines the values you want to match in the query results, and can include one or more of the following:
context
Limits query results based on the context, that is the location in the structure from where you start the query.
namespace
Where NAMESPACE is the namespace where the external data is made available.
If defined at a higher level of the query, the namespace does not need to be separately specified here.
id
Where IDENTIFIER is the unique identifier provided by the external system.
type
Where TYPE refers to the external entity type.
searchText
Limits search results by matching search strings.
The value for SEARCH TEXT can include one or more comma-separated text strings.
type
Limits query results to entities with the same entity type
# Pagination
The following two parameters work together for data pagination:
first
The value for NUM_ITEMS sets the first number of matching items to retrieve.
For example, a value of "100" would return the first 100 items.
after
For all requests following the initial one, the value for CURSOR defines the starting point of the query.
Typically, in each subsequent request, you would set the value to whatever was returned as the "cursor" position of the last item returned in the preceding request.
... on TYPE
Defines the query response, where:
  • TYPE is the entity type and matches the TYPE value in the identity section.
  • RESPONSE_FIELD_1 to RESPONSE_FIELD_n are the specific data fields that you want to be returned in the response.
The GraphQL type definition of the entity type determines which fields are available in a response.

Example request and response

The first sample code block illustrates a request to retrieve the first ten products that include a specified text string. The second code block illustrates the corresponding response with the matching products along with the requested product details (some data removed in example for space considerations).

RequestResponse
{ externalItems(namespace:
  "magento", 
  filter: { 
    context: 
    { id: "Mg%3d%3d_Y2F0ZWdvcnk%3d" type: "MagentoCategory" } 
    searchText: "Hoodie"
  }, first: 10, after: "Ng==")
  { edges {
    cursor node {
      identity { id type } ...
      on ExternalContent { title }    }   
  }     
  }
}




































{
  "data": {
    "externalItems": {
      "edges": [
        {
          "cursor": "Nw==",
          "node": {
            "identity": {
              "id": "TUgwMS1YUy1CbGFjaw%3d%3d_Y29udGVudA%3d%3d",
              "type": "MagentoProduct"
            },
            "title": "Chaz Kangeroo Hoodie-XS-Black"
          }
        },
        {
          "cursor": "OA==",
          "node": {
            "identity": {
              "id": "TUgwMS1YUy1HcmF5_Y29udGVudA%3d%3d",
              "type": "MagentoProduct"
            },
            "title": "Chaz Kangeroo Hoodie-XS-Gray"
          }
        },
.
.
.
        {
          "cursor": "MTU=",
          "node": {
            "identity": {
              "id": "TUgwMS1NLU9yYW5nZQ%3d%3d_Y29udGVudA%3d%3d",
              "type": "MagentoProduct"
            },
            "title": "Chaz Kangeroo Hoodie-M-Orange"
          }
        },
        {
          "cursor": "MTY=",
          "node": {
            "identity": {
              "id": "TUgwMS1MLUJsYWNr_Y29udGVudA%3d%3d",
              "type": "MagentoProduct"
            },
            "title": "Chaz Kangeroo Hoodie-L-Black"
          }
        }
      ]
    }
  }
}