Developer docs

GraphQL basics

How the pieces fit together, what a request looks like, and the conventions every query shares.

View as Markdown

How the pieces fit#

  1. YouProduct feedAn XML file of your products at a public URL.
  2. SolenyaScheduled ingestFetches the feed on the index's schedule, hourly by default.
  3. SolenyaIndexYour searchable catalogue, with its own ranking settings.
  4. Your backendItem queryA GraphQL request for search, similar products or browse.
  5. SolenyaResult pageRanked products, plus a query_uuid that names this page.
  6. Browser or appEventsViews, cart adds and purchases, carrying the query_uuid.
  7. SolenyaPersonalisationEach shopper's views shape the next page they see.
Each step feeds the next. Events with a query_uuid tie what shoppers did to the page that showed it.
PieceWhat it is
FeedYour product catalogue as a Google-format XML file at a public URL.
IndexA searchable copy of one feed, refreshed on a schedule, with its own ranking settings. One feed can back several indexes, for example staging and production.
ShopperSomeone browsing your shop, named by a UUID you create and keep. There is nothing to register: Solenya creates the shopper record the first time it sees the UUID.
ItemA product or variant from the feed, returned by the items query.

Endpoint and request#

All GraphQL operations go to one endpoint:

Text
POST https://api.solenya.ai/v1/graphql

The body is JSON with query and, optionally, variables and operationName. Every request needs the required headers. Field and argument names are written in snake_case, exactly as in the schema.

JSON
{
  "query": "query Feeds { feeds { page { rows { record { url } } } } }",
  "variables": {}
}

The answer is JSON with data, plus errors when something went wrong. See Errors and limits for both.

Lists and pages#

Every list (feeds, indexes, items, experiments, team members) comes back in the same wrapper. You ask for one page and read the rows inside it:

query Indexes {
  indexes {
    page(page_size: 25, page_number: 1) {
      rows {
        record {
          uuid
          name
        }
      }
      page_info {
        has_next_page
      }
    }
  }
}
  • page_size defaults to 25; item pages take up to 100. page_number starts at 1.
  • rows[].record holds the object itself. Some lists add rows[].metadata, such as an item's ranking score.
  • On item pages, has_next_page is true when the page came back full. A full last page also says true, and the next page is then empty.
  • Lists that take a filter take it as filter_term, with the same where / and / or / not shape described in Filters and facets.

The GraphQL explorer#

api.solenya.ai/v1/graphql opens in the browser as an explorer: browse the schema and its descriptions, and run queries. It sends no credentials of its own, so open its Headers panel and add yours before running anything:

JSON
{
  "Authorization": "Bearer <api_key>",
  "Solenya-Index-UUID": "<index_uuid>",
  "Solenya-User-UUID": "<user_uuid>"
}

Each GraphQL example in these docs has an Open in explorer link that loads it there.

Where to go next#

ToRead
Add feeds, create indexes, check ingestsFeeds and indexes
Search, show similar products, personaliseSearch and recommendations
Narrow results and count filter optionsFilters and facets