# GraphQL basics

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

## How the pieces fit

1. **Product feed** (You): An XML file of your products at a public URL.
2. **Scheduled ingest** (Solenya): Fetches the feed on the index's schedule, hourly by default.
3. **Index** (Solenya): Your searchable catalogue, with its own ranking settings.
4. **Item query** (Your backend): A GraphQL request for search, similar products or browse.
5. **Result page** (Solenya): Ranked products, plus a query_uuid that names this page.
6. **Events** (Browser or app): Views, cart adds and purchases, carrying the query_uuid.
7. **Personalisation** (Solenya): Each 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.

| Piece | What it is |
|-------|------------|
| Feed | Your product catalogue as a [Google-format](https://support.google.com/merchants/answer/7052112) XML file at a public URL. |
| Index | A 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. |
| Shopper | Someone 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. |
| Item | A product or variant from the feed, returned by the `items` query. |

## Endpoint and request

All GraphQL operations go to one endpoint:

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

The body is JSON with `query` and, optionally, `variables` and `operationName`. Every request needs the [required headers](https://solenya.ai/docs/auth.md#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](https://solenya.ai/docs/errors.md) 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:

```graphql
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](https://solenya.ai/docs/filters.md#how-a-filter-is-built).

## The GraphQL explorer

[api.solenya.ai/v1/graphql](https://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

| To | Read |
|----|------|
| Add feeds, create indexes, check ingests | [Feeds and indexes](https://solenya.ai/docs/setup.md) |
| Search, show similar products, personalise | [Search and recommendations](https://solenya.ai/docs/search.md) |
| Narrow results and count filter options | [Filters and facets](https://solenya.ai/docs/filters.md) |
