Developer docs

Feeds and indexes

Register your product feed, create an index over it, and check that each scheduled ingest succeeded.

View as Markdown

Most teams do this once, in the Console under Developer tools → Settings → Feeds and Indexes. The GraphQL mutations below do the same thing and need a team member's session token: adding or deleting a feed needs customer:write, and creating an index needs index:write:*. A secret API key can't do either.

Feed requirements#

Solenya fetches your feed from its URL and checks every item. One invalid item fails the whole ingest, so check a new feed before adding it.

RequirementDetail
FormatRSS 2.0 XML with the Google g: namespace, served plain or gzipped
ReachableThe URL is public and answers a HEAD request with a 2xx status. Keep it stable: Solenya re-fetches it on every ingest.
Fields Solenya usesid, title, description, link, image_link, price, availability, brand; also item_group_id, sale_price, product_type, size and color when you have them
price, sale_priceAn amount, a space and a currency code, such as 49.99 ZAR. No thousands separators.
id, item_group_idLetters, digits, spaces, _, - and / only
availabilityin_stock, out_of_stock, preorder or backorder. in stock and out of stock are also accepted.

See Google's product data specification for what each field means.

Feeds#

Add a feed#

mutation AddFeed {
  add_feed(feed_url: "https://shop.example.com/feed.xml") {
    url
  }
}

List and delete feeds#

query Feeds {
  feeds {
    page {
      rows {
        record {
          url
        }
      }
    }
  }
}
mutation DeleteFeed {
  delete_feed(feed_url: "https://shop.example.com/feed.xml") {
    url
  }
}

Indexes#

An index is a searchable copy of one feed with its own settings. Use several indexes over the same feed to keep staging apart from production, or to run different storefronts.

Create an index#

mutation AddIndex {
  add_index(
    feed_list: ["https://shop.example.com/feed.xml"]
    name: "Production"
    ingest_schedule: "0 * * * *"
  ) {
    uuid
    name
  }
}
ArgumentMeaning
feed_listThe feed to index. Register it with add_feed first.
nameA label for you
ingest_scheduleHow often Solenya re-fetches the feed, as a cron expression. Defaults to "0 * * * *", every hour.
tracking_mechanismWhere shopper preferences come from: inferred (the default) learns from every item request; event_based learns from view_item events.
servingOptional ranking settings. The two model ids can only be set later, with update_index.

Save the returned uuid: it is the Solenya-Index-UUID header on every item query.

Ingest schedule#

A new index's schedule starts switched off, so no ingest runs until you switch it on. Do that by setting the schedule once with update_index:

mutation StartIngest {
  update_index(index_uuid: "<index_uuid>", ingest_schedule: "0 * * * *") {
    uuid
  }
}

An invalid cron expression is rejected with Invalid cron expression.

Check an ingest#

Each index has a deployment: its schedule and its recent ingest runs.

query IngestRuns {
  indexes {
    page {
      rows {
        record {
          uuid
          name
          deployment {
            schedules {
              active
              schedule {
                cron
                timezone
              }
            }
            runs(limit: 5) {
              state_type
              expected_start_time
              start_time
              end_time
              total_run_time
              logs(limit: 20) {
                timestamp
                level_name
                message
              }
            }
          }
        }
      }
    }
  }
}
state_typeMeaning
SCHEDULED, PENDINGWaiting to start
RUNNINGFetching and indexing the feed
COMPLETEDDone; the catalogue is up to date
FAILED, CRASHEDThe ingest did not finish. Read logs for the reason, such as an invalid item or an unreachable URL.
CANCELLED, CANCELLING, PAUSEDStopped before it finished

runs returns up to 10 runs unless you pass limit, and each run's logs up to 20 lines.

Change an index#

Pass only the fields you want to change. feed_list takes one feed per call, and a call that changes feed_list ignores ingest_schedule, so change the schedule in its own call.

mutation ChangeFeed {
  update_index(
    index_uuid: "<index_uuid>"
    feed_list: ["https://shop.example.com/new-feed.xml"]
  ) {
    uuid
  }
}
mutation DeleteIndex {
  delete_index(index_uuid: "<index_uuid>") {
    uuid
  }
}

Serving config#

An index's serving config is its set of ranking settings. Set them on the index with update_index(serving: ...), or with add_index for every field except the two model ids. One request can override them with merchant_feed(serving: ...), and inherits whatever it leaves out.

FieldAffectsWhat it does
query_model_idText and image searchThe model that turns a search into something comparable with your products. Must suit the index; see the models query below.
score_cutoffText searchDrops results whose relevance score is below this, from 0 to 1. 0 turns it off. It only works where Solenya has calibrated the index's scores, and not with a different query_model_id, so ask Solenya before relying on it.
preference_model_idPersonalisationThe model that learns each shopper's taste. Must suit the index.
temperaturePersonalisationHow much variety personalised pages get. 0 or more; higher means more variety.
default_promptCategory pagesThe text that ranks a browse page with no search, product or image.
cold_startPersonalised category pagesWhat a shopper with no history sees: default_prompt (the default) ranks by the prompt above; persona_mix mixes in products from each of the preference model's personas.

A request that sets a field its traffic can't use is rejected. To see which models an index can use, ask for compatible_models with kind set to embedding (search) or preference (personalisation):

query CompatibleModels {
  indexes {
    page {
      rows {
        record {
          uuid
          serving {
            query_model_id
            preference_model_id
            temperature
          }
          compatible_models(kind: preference) {
            id
            repo_id
            embedding_dimension
          }
        }
      }
    }
  }
}

List indexes#

query Indexes {
  indexes {
    page {
      rows {
        record {
          uuid
          name
          tracking_mechanism
          feeds {
            url
          }
        }
      }
    }
  }
}

ingest_schedule on an index is deprecated. Read the schedule from deployment.schedules instead.