Review a dataset and propose a schema

Importing data usually starts with a guess. You look at your records, decide which field is the title, which one is a facet, which one holds the price, and create a collection schema by hand. If the guess is wrong you find out later, from bad search results.

The dataset review turns that guess into a measurement. You submit a sample of your records — or a whole small file — and the platform returns:

• a profile of the sample: the fields it found, their observed types, and how completely they are filled;
• a proposal: a ready-to-use mapping of your fields to roles such as title, price or category, including the resulting schema and query_by;
• a capability assessment: which platform features that data can support.

Nothing is written until you confirm.

Before you begin

• A full API key — confirming a profile writes against a collection.
• A representative sample: up to 100 documents or 2 MB of text.
• No collection needed for the preview itself. Reviewing is how you decide what to create.

What you'll build

A collection schema you did not have to invent, and a stored, agreed profile that later imports follow.

Steps

1. Submit the sample

curl -X POST https://api.aacsearch.com/v1/ingest/preview \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": "documents",
    "documents": [
      { "id": "1", "title": "Cordless drill 18V", "brand": "Acme", "price": 89.0, "in_stock": true },
      { "id": "2", "title": "Impact driver 18V", "brand": "Acme", "price": 119.0, "in_stock": false }
    ]
  }'

source selects how the sample is read:

For text sources, send content instead of documents — mixing them is a 400. Use source_name to label the origin, and total_count to say your real dataset is larger than the sample.

Optionally pass roles to assert what you already know, for example {"price": "price"}, so the proposal starts from your knowledge instead of inferring it. Fields you set are reported with role_source: "explicit"; inferred ones are "inferred".

Expected result: a 200 with profile, proposal and capabilities.

2. Read the profile

{
  "profile": {
    "version": 1,
    "sample_count": 2,
    "truncated": false,
    "fields": [
      {
        "name": "title",
        "types": ["string"],
        "present_count": 2,
        "null_count": 0,
        "coverage": 1,
        "role": "title",
        "role_source": "inferred",
        "reasons": ["unique text with high coverage"]
      }
    ],
    "domain_candidates": ["commerce", "generic"],
    "warnings": []
  },
  "proposal": { "fields": [], "query_by": [], "roles": {}, "…": "…" },
  "capabilities": [{ "id": "keyword_search", "data": "candidate", "…": "…" }]
}

The profile describes the sample, not your whole dataset:

3. Check which capabilities the data supports

capabilities[] answers the question that matters before you build on the schema. Each entry has an id — keyword_search, facets, semantic_search, image_search, assistant or recommendations — and assesses one dimension:

Only data is judged from your sample. Plan entitlement and configuration are checked elsewhere — see limits and billing.

Verify: the capabilities you intend to use report data: "candidate". If one does not, add the missing field at the source and submit the sample again — the preview has no side effects, so iterate here rather than after importing.

4. Confirm the profile

Confirming stores the accepted proposal against a collection, so later imports follow the agreed roles instead of re-inferring them.

curl -X PUT https://api.aacsearch.com/v1/collections/products/profile \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": "documents",
    "documents": [ { "id": "1", "title": "Cordless drill 18V", "price": 89.0 } ],
    "roles": { "title": "title", "price": "price" }
  }'

The body uses the same shape as the preview — the sample and any roles you settled on. Confirming re-runs the profile and stores the result.

Expected result: the stored profile, in the same shape as the preview response.

Verify: GET /collections/products/profile returns it. Confirming again replaces it, so a later import follows the newer decision.

Common problems

Next

• Incremental indexing — create the collection and import at scale.
• CMS connectors — the same review inside the Sources workflow.
• Search profiles and releases — what to configure once the schema is set.