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 constrained SQL endpoint supports one-table SELECT queries over captures, items, or changes. It does not support joins or unrestricted ClickHouse access.

Use the Explore API and dashboard for current markets, cross-store relationships, Variant history, and other views that depend on Extend entities. 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 constrained SQL endpoint. 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 Extend 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 public SQL endpoint enforces a timeout and result limit, but callers should still avoid unbounded scans. See the semantic model for the supported SQL fields.