Query semantics - Extralt Docs

Correct analysis depends on what one record represents and when it was observed, not only on field names.

Choose the right surface

The dashboard AI query flow supports one-table SELECT queries over captures, items, or changes. It is a first-party internal service, not a public v1 endpoint, and it does not support joins or unrestricted ClickHouse access.

Use public Explore v1 for current markets and Variant evidence. The dashboard also exposes beta change and relationship views that do not yet have dedicated public routes. Use OpenAPI for exact filters and payloads.

Organization scope

The authenticated organization determines the customer dataset. Identifiers should only be interpreted within that dataset unless a response explicitly defines a broader scope.

Current Offers

Offers are observations. The current Offer set for a Listing is all Offers from that Listing's latest observation, not one latest seller row.

This matters for marketplace and multi-SKU pages. Selecting one latest row can leave old sellers or sizes in the apparent current state after they disappear from a later observation. Purpose-built Explore responses apply the product's current-state rule.

Relationships

The primary analytical path is:

Offer -> Listing -> Variant -> Product
           |-> Store
           |-> Review

These are semantic relationships, not joins available through the dashboard AI query service. Use Explore for supported relationship views.

Time meanings

Field	Meaning
`run_started_at`	Time the source page was observed by an Extract Run
`published_at`	Source-reported publication date when available
`first_seen_at`	First valid Listing observation in this dataset
`last_seen_at`	Most recent valid Listing observation
`removed_at`	Explicit removal observation; null means active in the current model
`first_known_at`	First time a Variant became known to this dataset
`observed_at`	Time recorded on a Change event

“New” should mean first observed in this dataset unless an external launch date is explicitly available. Stores can be observed at different times; do not describe asynchronous observations as one synchronized market snapshot.

Country and currency

Store and Listing context is country-specific. Partition comparisons by country by default.

Do not aggregate or compare prices across currencies without an explicit conversion source and timestamp. Extralt does not currently provide currency conversion.

Availability and stock

Availability is an observed source fact. For Store x Variant analysis, the useful default is available when any current comparable Offer for that Store and Variant is available. Keep seller-level availability separate so a marketplace with many sellers does not overweight the result.

Stock level is categorical. Do not infer units on hand, future stock, lost sales, or continuous outage duration between observations.

Reviews

Review entities contain a current aggregate count and a score normalized to 0-100. When combining review aggregates, weight scores by review count and report coverage. Extralt does not currently provide review text, sentiment, or review history.

Missing values

A schema default is not necessarily a measured fact. Empty text, empty arrays, or zero-valued source fields can mean that the source did not expose a value. Check source evidence and coverage before interpreting absence as zero, false, or unavailable.

Coverage and freshness

An analysis should state:

stores and countries included;
currencies and product conditions included;
observation-time range;
matched, unmatched, included, and excluded counts where relevant;
whether cross-store matching is required for the result.

This prevents observed assortment or price coverage from being presented as complete market coverage.

SQL query safety

Select only the columns you need, filter by source and time early, and keep the result bounded. The machine-only dashboard query service returns at most 100 rows, caps buffered results at 512 KB, and applies a 35-second service timeout. The ClickHouse reader role supplies additional execution, scan, memory, and thread ceilings. See the semantic model for the fields currently available to dashboard AI queries.