Tables & Schema Reference¶
Working with an agent?
Claude has this page in its workspace, so you can ask which table carries a metric, what a column means, or how two tables join, and get the answer from the same source you are reading. See Getting Started With Agents.
All tables are queried through DuckDBClient or PolarsClient. Each table has a corresponding schema class that validates the returned DataFrame.
Import any schema from dda_sdk:
Available tables¶
| Table | Schema class | Description |
|---|---|---|
sales_per_sku |
SalesPerSkuSchema |
Daily sales metrics at SKU level |
sales |
SalesSchema |
Daily sales metrics aggregated per product |
events |
EventsSchema |
Promotional events with performance metrics (one row per event) |
visibility |
VisibilitySchema |
Store page visibility metrics by traffic source |
wishlist_actions |
WishlistActionsSchema |
Daily wishlist add/delete and conversion actions per product |
wishlist_cohorts |
WishlistCohortsSchema |
Wishlist conversion data grouped by cohort month |
products |
ProductsSchema |
Product catalogue |
skus |
SkusSchema |
SKU catalogue with human-readable names |
countries |
CountriesSchema |
Country codes, names, and regions |
currencies |
CurrenciesSchema |
Currency codes and symbols |
portals |
PortalsSchema |
Storefront and platform identifiers |
organizations |
OrganizationsSchema |
Organization metadata |
baseline |
BaselineSchema |
Baseline and uplift metrics per product |
Conventions¶
Currency: Unless a column's description explicitly states otherwise, all monetary columns (net_sales, gross_sales, gross_returned, and the baseline_*/uplift_* sales columns) are denominated in USD. The currency_code column on countries and the currencies table describe a country's local currency for reference/display purposes only — they do not indicate the denomination of any monetary metric.
sales_per_sku¶
Schema class: SalesPerSkuSchema
Daily sales metrics at SKU level. Use this when you need SKU-level detail or the human-readable human_name column. For product-level aggregation, prefer sales.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
unique_sku_id |
str | Globally unique identifier for a SKU across all portals/sources. |
base_sku_id |
str | Raw ID as seen in the source without any transformations. |
human_name |
str | null | Latest display name for the SKU sourced from external data. |
product_name |
str | null | Name of the product. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
organization_id |
str | Organization identifier. |
country_code |
str | Country code (ISO 3166 alpha-3). |
is_retail_sale |
bool | Indicates whether the sale is a retail sale (True) or not (False). |
bundle_name |
str | Name of the bundle. "NOT_APPLICABLE" or "Direct Package Sale" for non-bundled sales. |
is_bundled_sale |
bool | Indicates whether the sale is a bundl sale (True) or not (False). |
net_sales |
float | Revenue excluding refunds and taxes, before the portal's fee is deducted, denominated in USD. |
net_sales_approx |
float | Approximate revenue excluding refunds and taxes, after the portal's fee is deducted, denominated in USD. It applies each portal's standard fee to net_sales: 12% for Epic, 15% to 30% for Google, 30% for the rest. Where a portal reports its actual developer proceeds, those are used instead. The fee is an estimate rather than a settled payout, so treat the result as an approximation. |
gross_sales |
float | Gross revenue before refunds are deducted, denominated in USD. Refunded revenue is included here and also reported on its own in gross_returned. |
gross_returned |
float | Refunded revenue, expressed as a number denominated in USD. It is already included in gross_sales; subtract it to get revenue after refunds. |
units_returned |
int | Number of units returned by customers. |
units_sold_directly |
int | Number of units sold directly to customers. |
units_freely_distributed |
int | Number of units distributed for free. |
units_sold_in_retail |
int | Number of units sold in retail. |
all_units |
int | Net sold units across all channels: units_sold_directly + units_freely_distributed + units_sold_in_retail + units_returned. |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
sales¶
Schema class: SalesSchema
Daily sales metrics aggregated at the product level. Same columns as sales_per_sku except unique_sku_id, base_sku_id, human_name, product_name, and all_units — values are rolled up across all SKUs for a product.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
organization_id |
str | Organization identifier. |
country_code |
str | Country code (ISO 3166 alpha-3). |
retailer_tag |
str | null | Tag associated with the retailer. |
is_retail_sale |
bool | Indicates whether the sale is a retail sale (True) or not (False). |
bundle_name |
str | Name of the bundle. "NOT_APPLICABLE" or "Direct Package Sale" for non-bundled sales. |
is_bundled_sale |
bool | Indicates whether the sale is a bundl sale (True) or not (False). |
net_sales |
float | Revenue excluding refunds and taxes, before the portal's fee is deducted, denominated in USD. |
net_sales_approx |
float | Approximate revenue excluding refunds and taxes, after the portal's fee is deducted, denominated in USD. It applies each portal's standard fee to net_sales: 12% for Epic, 15% to 30% for Google, 30% for the rest. Where a portal reports its actual developer proceeds, those are used instead. The fee is an estimate rather than a settled payout, so treat the result as an approximation. |
gross_sales |
float | Gross revenue before refunds are deducted, denominated in USD. Refunded revenue is included here and also reported on its own in gross_returned. |
gross_returned |
float | Refunded revenue, expressed as a number denominated in USD. It is already included in gross_sales; subtract it to get revenue after refunds. |
units_returned |
int | Number of units returned by customers. |
units_sold_directly |
int | Number of units sold directly to customers. |
units_freely_distributed |
int | Number of units distributed for free. |
units_sold_in_retail |
int | Number of units sold in retail. |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
events¶
Schema class: EventsSchema
One row per promotional event. Deduplicate on event_id to get one row per event. Join to sales on regional_product_id + portal_platform_region to measure revenue uplift.
| Column | Type | Description |
|---|---|---|
event_id |
str | Globally unique identifier for an event. |
date_from |
date | Start date of a period. |
date_to |
date | End date of a period. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
organization_id |
str | Organization identifier. |
discount |
float | Discount value between 0 and 1. |
promo_length |
int | Length of the promotion in days. |
event_status |
str | null | Status of the event (finished or ongoing). |
event_name |
str | null | Name of the event. |
click_through_rate |
float | null | Non-owner visits to non-owner impressions ratio. Can be null if there are no impressions. |
conversion_rate |
float | null | Ratio of units sold directly to non-owner visits. Null when there are no non-owner visits. |
sales_uplift_score |
float | null | Ratio of total gross sales (baseline + uplift) to baseline gross sales. Values above 1 indicate positive uplift, below 1 indicate negative uplift. Null when baseline gross sales is zero. |
visibility¶
Schema class: VisibilitySchema
Daily store page visibility metrics broken down by traffic source. Join to sales on date + regional_product_id + portal_platform_region to correlate traffic with sales.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
organization_id |
str | Organization identifier. |
non_owner_visits |
int | Number of store page visits by users who do not own the product. |
non_owner_impressions |
int | Number of store page impressions. |
owner_visits |
int | Number of store page visits by users who own the product. |
owner_impressions |
int | Number of store page impressions. |
visit_source |
str | Indicates how the user arrived at the store page. 'Direct Navigation' when visits occurred with no impressions (user navigated directly), 'Visits from Impressions' when visits originated from store page impressions. |
hash_traffic_source |
str | Trafic source identifier |
page_category |
str | Page category (e.g. Sales Page, Bot Traffic) |
page_feature |
str | Page feature (e.g. New and Trending, Top Sellers List) |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
wishlist_actions¶
Schema class: WishlistActionsSchema
Daily wishlist add, delete, and conversion actions at the product level. Join to sales on date + regional_product_id + portal_platform_region to correlate wishlist activity with sales.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
country_code |
str | Country code (ISO 3166 alpha-3). |
organization_id |
str | Organization identifier. |
adds |
int | Number of times the product was added to wishlists. |
deletes |
int | Number of times the product was removed from wishlists. |
purchases_and_activations |
int | Number of wishlist items purchased or activated. |
gifts |
int | Number of wishlist items gifted to other users. |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
wishlist_cohorts¶
Schema class: WishlistCohortsSchema
Wishlist conversion data grouped by the month in which users added the product to their wishlist. Use this to understand how quickly users convert from wishlist to purchase over time.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
month_cohort |
date | First day of the calendar month representing the cohort period. |
organization_id |
str | Organization identifier. |
total_conversions |
int | Total number of conversions (purchases, activations, and gifts combined). |
purchases_and_activations |
int | Number of wishlist items purchased or activated. |
gifts |
int | Number of wishlist items gifted to other users. |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
baseline¶
Schema class: BaselineSchema
Estimated counterfactual sales — what would have happened without promotional effects. Each row pairs a baseline_* value (the modelled trend) with an uplift_* value (the incremental impact of the promotion). is_promo_sale flags rows that fall within a promotional period.
| Column | Type | Description |
|---|---|---|
date |
date | Date value. |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
portal_platform_region |
str | Combination of portal, platform and region. |
organization_id |
str | Organization identifier. |
country_code |
str | Country code (ISO 3166 alpha-3). |
is_promo_sale |
bool | Indicates whether the sale occurred during a promotional period (True) or not (False). |
baseline_units_sold_directly |
int | Estimated counterfactual units sold directly: the volume that would have been sold directly absent promotional and other event effects. Computed through the baseline pipeline. |
baseline_units_freely_distributed |
int | Estimated counterfactual units freely distributed absent promotional and other event effects. Computed through the baseline pipeline. |
baseline_units_sold_in_retail |
int | Estimated counterfactual units sold in retail absent promotional and other event effects. Computed through the baseline pipeline. |
baseline_units_returned |
int | Estimated counterfactual units returned absent promotional and other event effects. Computed through the baseline pipeline. |
baseline_gross_sales |
float | Estimated gross revenue under normal conditions, before refunds are deducted, denominated in USD. Refunded revenue is included here and also reported on its own in baseline_gross_returned. Represents natural sales performance as a neutral benchmark, not a forecast or target. |
baseline_gross_returned |
float | Estimated refunded revenue under normal conditions, expressed as a number denominated in USD. It is already included in baseline_gross_sales; subtract it to get baseline revenue after refunds. |
baseline_net_sales |
float | Estimated net sales under normal conditions, denominated in USD, excluding refunds and taxes and before the portal's fee is deducted. Serves as a neutral benchmark to identify when reality diverges from usual patterns. |
baseline_net_sales_approx |
float | Approximate estimated net sales under normal conditions, denominated in USD, excluding refunds and taxes and after the portal's fee is deducted. The fee is an estimate based on the portal's standard rate. |
uplift_units_sold_directly |
int | Units sold directly uplift: incremental impact as realized_units_sold_directly minus baseline_units_sold_directly. Isolates the effect of promotions and other events. |
uplift_units_freely_distributed |
int | Units freely distributed uplift: incremental impact of promotions and other events. |
uplift_units_sold_in_retail |
int | Units sold in retail uplift: incremental impact of promotions and other events. |
uplift_units_returned |
int | Units returned uplift: incremental impact of promotions and other events. |
uplift_gross_sales |
float | Difference between actual and baseline gross revenue, before refunds are deducted, denominated in USD. Refunded revenue is included here and also reported on its own in uplift_gross_returned. Captures the incremental effect of promotions, discounts, launches, or other unusual activity. |
uplift_gross_returned |
float | Difference between actual and baseline refunded revenue, denominated in USD. It is already included in uplift_gross_sales. Positive values indicate more refunds than expected; negative values indicate fewer. |
uplift_net_sales |
float | Difference between actual and baseline net sales, denominated in USD, excluding refunds and taxes and before the portal's fee is deducted. Captures the incremental revenue effect. |
uplift_net_sales_approx |
float | Approximate difference between actual and baseline net sales, denominated in USD, excluding refunds and taxes and measured after the portal's fee is deducted. The fee is an estimate based on the portal's standard rate. |
products¶
Schema class: ProductsSchema
Product catalogue — one row per product per storefront.
| Column | Type | Description |
|---|---|---|
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
organization_id |
str | Organization identifier. |
portal_platform_region |
str | Combination of portal, platform and region. |
product_name |
str | null | Name of the product. |
product_type |
str | null | Type of the product (e.g. game, soundtrack, paid_addon, etc.). |
custom_group |
str | null | Custom group for the products. |
skus¶
Schema class: SkusSchema
SKU catalogue with human-readable names and type metadata.
| Column | Type | Description |
|---|---|---|
unique_sku_id |
str | Globally unique identifier for a SKU across all portals/sources. |
base_sku_id |
str | Raw ID as seen in the source without any transformations. |
portal_platform_region |
str | Combination of portal, platform and region. |
human_name |
str | null | Latest display name for the SKU sourced from external data. |
product_name |
str | null | Name of the product. |
product_type |
str | null | Type of the product (e.g. game, soundtrack, paid_addon, etc.). |
regional_product_id |
str | Hashed combination of product_name, portal_platform_region and organization_id. |
custom_group |
str | null | Custom group for the products. |
sku_type |
str | null | Sales (buyable SKUs, sales-level observations) or Store (non-buyable store-level entities used for visibility/wishlist/DAU/MAU on some platforms). |
organization_id |
str | Organization identifier. |
release_date |
date | null | Date the SKU was released. Nullable — some SKUs lack a release date. |
countries¶
Schema class: CountriesSchema
Country dimension table. Join to sales tables on country_code for geographic breakdowns.
| Column | Type | Description |
|---|---|---|
country_code |
str | Country code (ISO 3166 alpha-3). |
country_code_alpha2 |
str | null | Country code (ISO 3166 alpha-2). |
country_name |
str | Name of the country. |
region |
str | null | Region the country belongs to. |
currency_code |
str | null | Currency code (ISO 4217) of the country's local currency, for reference/display only. Monetary columns elsewhere (e.g. net_sales, gross_sales) are denominated in USD unless their description states otherwise. |
currencies¶
Schema class: CurrenciesSchema
Currency dimension table describing each country's local currency, for reference/display only (e.g. showing a currency's name or symbol). It has no bearing on the denomination of monetary metrics such as net_sales or gross_sales, which are in USD — see Conventions. Join to countries on currency_code.
| Column | Type | Description |
|---|---|---|
currency_code |
str | Currency code (ISO 4217). |
currency_name |
str | Name of the currency. |
symbol |
str | Symbol of the currency. |
portals¶
Schema class: PortalsSchema
Storefront dimension table. Lists every portal/platform/region combination available in your data, along with the latest date for which data has been received. Always query this table before constructing portal_platform_region filters. Use DisplayPortal for human-friendly storefront names in reports.
| Column | Type | Description |
|---|---|---|
portal_platform_region |
str | Portal platform region identifier - Concatenated field of portal, platform and region (e.g. steam:PC:Global). Primary key. |
portal |
str | Portal name (e.g. steam, nintendo, playstation). |
display_portal |
str | Portal human friendly name (e.g. Steam, Nintendo, PlayStation). |
platform |
str | Platform name (e.g. PC, Switch 2, PS5). |
store |
str | Store name or identifier within a portal. |
region |
str | Region name (e.g. Global, Nintendo Japan, PS America). |
latest_date |
date | null | The latest date for which data is available for the portal/platform/region combination. |
organizations¶
Schema class: OrganizationsSchema
Organization lookup table.
| Column | Type | Description |
|---|---|---|
organization_id |
str | Organization identifier. |
organization_name |
str | Name of the organization. |