---
name: luminate
parent_skill: partners
description: "Luminate music industry data — streaming, sales, airplay, charts, market share across 50+ countries."
last-reviewed: 2026-04-01
---

# Luminate Data Skill

## Overview

Luminate provides comprehensive music industry data covering streaming consumption, physical/digital sales, airplay monitoring, chart performance, and market share. Data is delivered via a Snowflake datashare and supplemented by internal aggregate models for improved query performance.

The data covers 6 core entity types: Musical Recordings (ISRCs), Songs, Musical Products (barcodes), Musical Releases, Musical Release Groups (albums), and Artists — with consumption metrics across 50+ countries.

## Data Locations

There are two databases. Use the catalog (DESCRIBE or `#table` syntax) to inspect column details — do NOT rely on memory for column names.

| Database | Schema | What It Contains |
|----------|--------|-----------------|
| `LUMINATE_DB_LISTING_DETAIL` | `EXTRACT_S` | **Vendor datashare** — 41 views: metadata, fact (detail/summary/provider), reference, mapping, charts, airplay, and market share views |
| `LUMINATE_DB_LISTING_CLAIM` | `EXTRACT_S` | **Vendor datashare (claims)** — 7 views: claim-level fact data, business unit hierarchies, catalog codes, musical rights. Only for owned/distributed content |
| `LUMINATE_MODELS` | `PROD` | **Internal aggregate models** — pre-aggregated summary tables at period-end (RTD, WTD, YTD, RTCW) and monthly grain. Faster than querying raw datashare summary views directly |

## Routing

Match the analyst's question to the right reference file before writing queries.

| Question Type | Load |
|--------------|------|
| "What databases/schemas exist?", "What tables are available?", "Where does X data live?" | `references/data-overview.md` |
| "How do I join songs to albums?", "How are entities related?", mapping between IDs | `references/entity-relationships.md` |
| "How should I filter?", "What are the valid values for X?", cluster keys, performance | `references/query-guide.md` |
| "Show me an example query", common patterns, starting point for a query | `references/sample-queries.md` |
| "Detail vs Summary?", "What fact tables to use?", streaming/sales/airplay data | `references/consumption-facts.md` |
| "Are there pre-built aggregates?", "Monthly/WTD/YTD data", faster alternatives | `references/internal-models.md` |

> **Note**: `consumption-facts.md` and `internal-models.md` are extracted from `data-overview.md` per the template scaling guidance (each exceeds 50 lines).

## Workflow

### Step 0: Load Universal Standards

**Load** the parent skill's `references/query-standards.md` before proceeding. It contains universal rules for value discovery, aggregation, catalog usage, and date-range interpretation that apply to all queries below.

### Step 1: Understand the Request

1. Determine what the analyst wants: streaming counts, sales figures, chart positions, market share, airplay, or metadata lookups
2. Identify the entity level: Artist, Song, Musical Recording (ISRC), Musical Product (barcode), Musical Release, or Release Group (album)
3. Identify the geography and time range

### Step 2: Choose the Right Data Source

**Follow the data source preference order from `references/query-standards.md`** (pre-aggregated → summary → detail). Luminate's tiers:

1. **Internal models first** (`LUMINATE_MODELS.PROD`) — pre-aggregated, fastest, cheapest. Covers period-end (RTD, WTD, YTD, RTCW) and monthly grain for most entities. **Load** `references/internal-models.md` to check coverage.
2. **Summary datashare tables** — national-level daily data. Use when internal models lack the required date range, breakout, or entity type.
3. **Detail datashare tables** — most expensive. Use ONLY when metro-level, transaction-level, or provider-level granularity is explicitly needed.
4. **Claim tables** (`LUMINATE_DB_LISTING_CLAIM`) — restricted to owned/distributed content, US and CA only.

**Apply the date-range interpretation rules from `references/query-standards.md`** to determine whether a pre-aggregated model covers the analyst's time frame. Luminate's available model periods are: RTD, WTD, YTD, RTCW, and monthly.

**Load** `references/consumption-facts.md` for the full table comparison when deciding between summary and detail.
**Load** `references/query-guide.md` for Luminate-specific filters and performance rules.

### Step 3: Identify Tables and Joins

1. **Verify the correct database prefix** — datashare objects are split across `LUMINATE_DB_LISTING_DETAIL` and `LUMINATE_DB_LISTING_CLAIM`. The correct database varies per table. Use `references/data-overview.md` or the catalog to confirm the three-part name. Never guess the database.
2. Use the database catalog (`DESCRIBE TABLE` or `#table`) to verify column names on the chosen tables
3. **Load** `references/entity-relationships.md` if joining across entity types (e.g., songs to albums, recordings to products)
4. **Load** `references/query-guide.md` for Luminate-specific cluster keys and required filters
5. **Verify country availability** — not all data points are available for all countries. If the analyst asks about a specific country, confirm that Luminate provides that metric for that territory before writing the query.

### Step 4: Build the Query

1. Apply Luminate-specific rules from `references/query-guide.md`:
   - Always filter on REPORT_DATE, COUNTRY_CODE, and METRIC_CATEGORY
   - Use cluster keys for performance
   - Filter MARKET_ID = -1 for national data in Detail views to avoid double-counting
2. Apply universal rules from the parent's `references/query-standards.md` (value discovery, SUM quantities, catalog-first)
3. Self-check before presenting:
   - Are streaming and sales being accidentally mixed?
   - Is MARKET_ID filtered in Detail/Provider views?
   - Are breakout columns relevant to the metric type?

## Critical Caveats

- **METRIC_CATEGORY is mandatory** — without it, streams and sales get mixed together
- **MARKET_ID = -1 in Detail/Provider views** — omitting this doubles counts for US/CA (see `references/query-guide.md`)
- **LUMINATE_NULL** — the string `'LUMINATE_NULL'` (not SQL NULL) for inapplicable breakout values
- **CONTENT_TYPE** — only available for US, CA, and AA (Worldwide). Avoid filtering on this column for other countries as it has possible values for 'LUMINATE_NULL' or 'Total'
- **Streaming vs Sales breakouts differ** — see `references/query-guide.md` for column groupings
- **Claim data** — US and CA only, owned/distributed content only