{ "entries": [ { "terms": [ "statement period", "statement cycle", "royalty period", "period id", "p316", "close the books" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD"], "related": ["ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_PERIOD"], "context": "Statement periods are the top-level monthly accounting cycles in Abacus, identified by a sequential integer statement_period_id that increments by 1 each month. Each statement period has a statement_period_name (e.g. 'P316'), statement_month, statement_year, and statement_period_status. Statement periods are the parent of accounting periods, which in turn are the parent of accounting runs. Nearly every accounting query filters by statement_period_id. The statement_period_status field tracks whether the period is open, closed, or in progress.", "domain": "accounting", "priority": 2, "relationships": [ "STATEMENT_PERIOD -> ACCOUNTING_PERIOD (1:N, via statement_period_id, one per contract_type)", "STATEMENT_PERIOD -> ABACUS_EVENT (1:N, via statement_period_id, all events in this period)", "STATEMENT_PERIOD -> VW_ABACUS_BALANCES_LOOKER_V2 (1:N, via STATEMENT_PERIOD_ID)", "STATEMENT_PERIOD -> all REVENUE_BY_*_DBT tables (1:N, via statement_period_id)", "STATEMENT_PERIOD -> EXCHANGE_RATE (1:N, via statement_period_id, one set of currency conversion rates per period)" ], "businessRules": [ "Statement period close preconditions (all 5 required): (1) status must be CURRENT, (2) all accounting periods CLOSED, (3) all balances closed, (4) all payment entities visible to customer, (5) next sequential period (ID+1) must exist", "statement_period_status values: OPEN, CURRENT, CLOSED" ], "examples": [ { "question": "List the last 12 statement periods with their status", "query": "SELECT statement_period_id, statement_period_name, statement_month, statement_year, statement_period_status FROM STATEMENT_PERIOD ORDER BY statement_period_id DESC LIMIT 12", "variables": {} } ] }, { "terms": [ "accounting period", "accounting cycle", "contract type period" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_PERIOD"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN" ], "context": "Accounting periods are children of statement periods and define the contract_type scope for a royalty run. Each accounting period has an accounting_period_id, a parent statement_period_id, and a contract_type ('distribution', 'neighbouring_rights', etc.). An accounting period can have multiple accounting runs. The contract_type determines which sales and contracts are processed during the run.", "domain": "accounting", "priority": 1, "relationships": [ "ACCOUNTING_PERIOD -> STATEMENT_PERIOD (N:1, via statement_period_id)", "ACCOUNTING_PERIOD -> ACCOUNTING_RUN (1:N, via accounting_period_id)" ], "businessRules": [ "contract_type values: 'distribution', 'neighbouring_rights' - determines which contracts and sales are in scope" ] }, { "terms": [ "accounting run", "accounting results", "run results", "calculation output", "royalty run" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN_RESULTS"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN_RESULTS_DISTRO", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN_RESULTS_NR", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_PERIOD" ], "context": "Accounting runs are the core calculation process in Abacus that computes royalties for clients. Each run belongs to an accounting_period (which belongs to a statement_period) and a run_controller. Run statuses: NO_ACTION_TAKEN, IN_PROGRESS, COMPLETED, ERROR. ACCOUNTING_RUN_RESULTS contains the final calculated royalties per contract and statement period. Separate result tables exist for distribution (_DISTRO) and neighbouring rights (_NR). Key result columns: accounting_run_id, contract_txn_id, gross_revenue_payee_currency, net_revenue_payee_currency, gross_revenue_after_withholding_tax_payee_currency. NR results additionally include royalty_rate from contract_term_condition, withholding_tax columns, and sale/payee currency conversions. ACCOUNTING_RUN tracks run metadata: accounting_run_id, accounting_period_id, run_controller_id, run_status, start_date, end_date.", "domain": "accounting", "priority": 2, "businessRules": [ "Full run status machine: NO_ACTION_TAKEN -> WAITING_TO_RUN -> RUNNING -> COMPLETE -> COMMITTING -> COMMITTED (also: SKIPPED, ERROR, INVALID)", "INVALID auto-creates a clone run for the same controller; the original stays as historical record", "WAITING_TO_RUN sets start_date; COMPLETE or ERROR sets end_date" ], "gotchas": [ "Run statuses in the context field are simplified - the full machine has 8 states with specific allowed transitions", "Separate result tables exist for distribution (_DISTRO) and NR (_NR) - query the correct one based on contract_type" ], "examples": [ { "question": "Accounting run results for a specific run", "query": "SELECT arr.accounting_run_id, ar.run_status, ap.statement_period_id, SUM(arr.gross_revenue_payee_currency) AS total_gross, SUM(arr.net_revenue_payee_currency) AS total_net FROM ACCOUNTING_RUN_RESULTS arr JOIN ACCOUNTING_RUN ar ON ar.accounting_run_id = arr.accounting_run_id JOIN ACCOUNTING_PERIOD ap ON ap.accounting_period_id = ar.accounting_period_id WHERE ap.statement_period_id = :statement_period_id GROUP BY arr.accounting_run_id, ar.run_status, ap.statement_period_id", "variables": { "statement_period_id": "316" } } ] }, { "terms": [ "run controller", "run config", "contract grouping", "run controller contract" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_PERIOD", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.RUN_CONTROLLER", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.RUN_CONTROLLER_CONTRACT" ], "context": "Run controllers group contracts for processing during accounting runs. Each contract belongs to a run controller via run_controller_contract. Sibling contracts (same account_id and contract_type) must always be in the same run controller to avoid double-booking sales. VW_DIM_ABACUS_CONTRACT is the primary denormalized view joining contract, account_contract, run_controller_contract, contract_flowthrough, ledger_account_contract_current_balance, and reference tables. Key columns: contract_id, contract_type, account_id, current_balance, contract_flowthrough_id, flowthrough_rate, flowthrough_status, is_paythrough_contract, run_controller_id.", "domain": "accounting", "priority": 1, "relationships": [ "RUN_CONTROLLER -> CONTRACT (1:N, via run_controller_contract join table)", "RUN_CONTROLLER -> ACCOUNTING_RUN (1:N, via run_controller_id)", "VW_DIM_ABACUS_CONTRACT joins: contract + account_contract + run_controller_contract + contract_flowthrough + ledger_account_contract_current_balance + reference tables" ], "businessRules": [ "Sibling contracts (same account_id + contract_type) must be in the same run controller to prevent double-booking" ] }, { "terms": [ "account statement period", "statement period data", "account period" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.ACCOUNT_STATEMENT_PERIODS_DBT"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD", "ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_PERIOD" ], "context": "Account-level statement period data linking accounts to their statement periods with associated accounting periods. Shows which statement periods an account has data for, useful for determining an account's first and most recent activity periods.", "domain": "accounting", "priority": 2, "examples": [ { "question": "Statement periods with data for account 123", "query": "SELECT statement_period_id, accounting_period_id FROM ACCOUNT_STATEMENT_PERIODS_DBT WHERE account_id = :account_id ORDER BY statement_period_id DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "abacus event", "event system", "financial event", "ledger event" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.ABACUS_EVENT"], "related": ["ROYALTY_ACCOUNTING.{{env}}.ACCOUNTING_RUN"], "context": "Abacus events are the polymorphic event system driving all financial activity in royalty accounting. Every ledger entry, payment, adjustment, reserve, and accounting run is tied to an abacus_event. Key columns: abacus_event_id, statement_period_id, event_name, target_type, target_id, event_date, created_by. The target_type/target_id pair polymorphically references any table (accounting_run, statement_period, contract, etc.). Common event_names: send_payments, commit_batch_payment, payment_returned, take_reserves, release_reserves, apply_pending_adjustments, apply_royalty_reversal, apply_royalty_correction, commit_vat, commit_withholding_tax, confirm_advance_payment, commit_custom_payment.", "domain": "accounting", "priority": 1 }, { "terms": [ "exchange rate", "fx rate", "currency conversion", "currency code", "supported currencies", "available currencies" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.EXCHANGE_RATE" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD"], "context": "Exchange rates are published per statement period. Each row defines a conversion rate from one currency to another for that period. Key columns: exchange_rate_id, statement_period_id, rate, from_currency_code (3-char ISO), to_currency_code (3-char ISO). Exchange rates must be delivered before non-base-currency adjustments can be submitted for a period - the adjustment handler checks exchange_rates_delivered on the statement period before accepting submissions.", "domain": "accounting", "priority": 2, "relationships": [ "EXCHANGE_RATE -> STATEMENT_PERIOD (N:1, via statement_period_id, one set of rates per period)" ], "gotchas": [ "Exchange rates are scoped to a statement_period_id - always filter by period; rates can differ across periods", "A 422 on adjustment submission usually means exchange rates haven't been delivered for the target period" ], "examples": [ { "question": "What currency codes are supported?", "query": "SELECT DISTINCT from_currency_code FROM EXCHANGE_RATE ORDER BY from_currency_code", "variables": {} }, { "question": "Exchange rate from GBP to USD for statement period 316", "query": "SELECT from_currency_code, to_currency_code, rate FROM EXCHANGE_RATE WHERE statement_period_id = :period_id AND from_currency_code = :from_currency AND to_currency_code = :to_currency", "variables": { "period_id": "316", "from_currency": "GBP", "to_currency": "USD" } }, { "question": "All exchange rates for the current statement period", "query": "SELECT er.from_currency_code, er.to_currency_code, er.rate FROM EXCHANGE_RATE er JOIN STATEMENT_PERIOD sp ON er.statement_period_id = sp.statement_period_id WHERE sp.statement_period_status = 'CURRENT' ORDER BY er.from_currency_code, er.to_currency_code", "variables": {} } ] }, { "terms": [ "contract", "vendor contract", "royalty contract", "deal", "contract term", "royalty rate", "term conditions", "contract lifecycle", "carve-out", "carveout", "carve out", "contract status history", "contract transaction", "transaction detail", "royalty transaction", "contract denormalized", "flat contract", "contract flat view", "booked", "snapshot", "contract snapshot" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_OA_CONTRACT", "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_OA_CONTRACT_ACTIVE", "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_DBT", "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_OA_CONTRACT_TERM_ACTIVE", "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_TRANSACTION_DISTRO", "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_TRANSACTION_NR", "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_DENORMALIZED_DISTRO", "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_DENORMALIZED_NR" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT", "ROYALTY_ACCOUNTING.{{env}}.VW_CONTRACT_LIFECYCLE_HISTORY", "ROYALTY_ACCOUNTING.{{env}}.VW_FACT_CONTRACT_HISTORY", "ROYALTY_ACCOUNTING.{{env}}.VW_UPC_TO_CONTRACT_MAPPING" ], "context": "Abacus royalty contracts represent legal agreements between The Orchard and vendors/labels. Key columns: contract_id (PK), contract_name, contract_type ('distribution' or 'neighbouring_rights'), initial_start_date, execution_date, is_paythrough_contract. Contracts belong to accounts via account_contract (account_id = vendor_id in art_relations). CONTRACT_DBT combines Abacus and Workstation contracts. VW_OA_CONTRACT_ACTIVE shows only active contracts. VW_DIM_ABACUS_CONTRACT is the denormalized view with current_balance, flowthrough config, and run controller info. Contracts cannot be deleted if they have ledger activity. Sibling contracts (same account + contract_type) must stay in the same run controller. Contract terms define royalty rates and conditions: each contract can have multiple terms (term_type: 'label', 'product', 'isrc'), each with a royalty_rate (Number(5,4) as decimal, e.g. 0.8000 = 80%). During accounting runs, sales match to contracts by 'isrc' terms first, then 'product', then 'label'. Contract transactions contain the individual transaction records matched to contracts during runs; key columns: contract_txn_id, accounting_run_id, contract_id, account_id. Denormalized views flatten contract, terms, conditions, and party info for reporting. VW_CONTRACT_LIFECYCLE_HISTORY tracks status transitions over time. VW_DIM_ABACUS_AR_BOOKED_VENDOR_CONTRACT_SNAPSHOT captures point-in-time contract state for reconciliation. Contract lifecycle transitions (e.g., TO_BE_TERMINATED -> TERMINATED) are automated by the Run Controller during accounting runs - they are not triggered by users. The Run Controller groups contracts for batch processing. When a contract is excluded from accounting (isExcludedFromAccountingRun), it is skipped during runs but retains its current status.", "domain": "contracts", "priority": 2, "joins": [ { "from": "VW_OA_CONTRACT", "to": "LEDGER_ACCOUNT_CONTRACT", "relation": "contract_ledger_entries" }, { "from": "VW_OA_CONTRACT", "to": "FLOWTHROUGH", "relation": "contract_flowthrough" }, { "from": "CONTRACT_DBT", "to": "VW_DIM_ABACUS_CONTRACT", "relation": "contract_denormalized" }, { "from": "CONTRACT_TRANSACTION_DISTRO", "to": "ROYALTY_STATEMENT_DETAIL", "relation": "transaction_in_statement" } ], "relationships": [ "CONTRACT -> ACCOUNT (N:1, via account_contract.account_id where account_id = vendor_id)", "CONTRACT -> CONTRACT_TERM (1:N) -> CONTRACT_TERM_CONDITION (1:N) -> REFERENCE_TRANSACTION_TYPE (N:N)", "CONTRACT -> RUN_CONTROLLER (N:1, via run_controller_contract)", "CONTRACT -> CONTRACT_TRANSACTION_DISTRO / _NR (1:N, matched transactions per accounting run)", "CONTRACT -> LEDGER_ACCOUNT_CONTRACT (1:N, all ledger entries for this contract)" ], "businessRules": [ "Contract term matching priority during runs: 'isrc' terms first, then 'product', then 'label'", "royalty_rate stored as Number(5,4) decimal: 0.8000 = 80%; term_rate + commission = 100 (complements)", "Contract term types: artist, catalog, contribution, label, product, track, contributor_schedule, contribution_schedule", "Mechanical deduction territories: CAN, ROW, USA; types: digital, physical; admin types: both, business, customer", "Contracts cannot be deleted if they have ledger activity", "Default country exclusion: Russia (RUS) excluded from all new contracts" ], "gotchas": [ "Paythrough contracts have revenue flowing through adjustments (LEDGER_ADJUSTMENT tables), not standard balances", "CONTRACT_DBT combines Abacus and Workstation contracts - filter by source if needed" ], "examples": [ { "question": "Active contracts for account 123 with current balances", "query": "SELECT c.contract_id, c.contract_name, c.contract_type, c.current_balance, c.flowthrough_status, c.is_paythrough_contract FROM VW_DIM_ABACUS_CONTRACT c WHERE c.account_id = :account_id ORDER BY c.contract_id", "variables": { "account_id": "123" } }, { "question": "Contract terms and rates for a contract", "query": "SELECT contract_id, term_type, royalty_rate FROM VW_OA_CONTRACT_TERM_ACTIVE WHERE contract_id = :contract_id", "variables": { "contract_id": "12345" } } ] }, { "terms": [ "balance", "account balance", "closing balance", "opening balance", "ledger balance", "balance report", "what's our balance", "how much do we owe", "positive balance", "positive ledger balance" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_BALANCES_STAGING"], "context": "Account and contract balances from the Abacus ledger, structured for Looker reporting. This is the most comprehensive balance view with ~40 columns. Key columns: STATEMENT_PERIOD_ID, ACCOUNT_ID (= vendor_id), ACCOUNT_NAME, CONTRACT_ID, CONTRACT_NAME, ACCOUNT_PAYEE_CURRENCY (ISO 4217). Balance columns: OPENING_BAL (carried from previous period's LEDGER_BAL), GROSS_REVENUE, DIST_FEE (distribution fee, typically negative), NET_REVENUE (gross minus dist fee), MECHANICAL_DEDUCTION_TOTAL, MECHANICAL_DEDUCTION_ADMIN_FEE_TOTAL. Adjustments: APPLIED_ADJUSTMENTS, APPROVED_ADJUSTMENTS (approved but not applied), NOT_APPROVED_ADJUSTMENTS (pending). Reserves: RESERVES_TAKEN (negative, withheld), RESERVES_RELEASED (returned to balance). Payments: PAYMENT (negative, sent), PAYMENT_RETURNED, CUSTOM_PAYMENT, CUSTOM_PAYMENT_RETURNED. Advances: ADVANCE, ADVANCE_RETURN. Taxes: VAT_AMOUNT, WHT_AMOUNT, VAT_AMOUNT_RETURN, WHT_AMOUNT_RETURN. Royalty corrections: ROYALTY_REVERSALS, ROYALTY_CORRECTIONS. Balance formula: EST_CLOSING_BAL = OPENING_BAL + NET_REVENUE + MECHANICAL_DEDUCTION_ADMIN_FEE_TOTAL + MECHANICAL_DEDUCTION_TOTAL + APPLIED_ADJUSTMENTS + RESERVES_TAKEN + RESERVES_RELEASED + PAYMENT + PAYMENT_RETURNED + ADVANCE + ADVANCE_RETURN + VAT_AMOUNT + WHT_AMOUNT + VAT_AMOUNT_RETURN + WHT_AMOUNT_RETURN + ROYALTY_REVERSALS + ROYALTY_CORRECTIONS + CUSTOM_PAYMENT. DELTA = EST_CLOSING_BAL - LEDGER_BAL (should equal 0 when reconciled). PAYABLE_AMOUNT shows current positive balance available for payment. RUN_CONTROLLER_ID links to the processing controller. Revenue for paythrough contracts flows through adjustments (LEDGER_ADJUSTMENT_DETAIL and LEDGER_ADJUSTMENT_APPLIED tables), NOT the standard balances pipeline. If standard revenue queries return empty results for an account, check whether the contract is a paythrough - the revenue will appear in adjustment/flowthrough views instead.", "domain": "accounting", "priority": 2, "relationships": [ "VW_ABACUS_BALANCES_LOOKER_V2 -> STATEMENT_PERIOD (N:1, via STATEMENT_PERIOD_ID)", "VW_ABACUS_BALANCES_LOOKER_V2 -> ACCOUNT (N:1, via ACCOUNT_ID = vendor_id)", "VW_ABACUS_BALANCES_LOOKER_V2 -> CONTRACT (N:1, via CONTRACT_ID)", "VW_ABACUS_BALANCES_LOOKER_V2 -> RUN_CONTROLLER (N:1, via RUN_CONTROLLER_ID)" ], "businessRules": [ "EST_CLOSING_BAL = OPENING_BAL + NET_REVENUE + MECHANICAL_DEDUCTION_ADMIN_FEE_TOTAL + MECHANICAL_DEDUCTION_TOTAL + APPLIED_ADJUSTMENTS + RESERVES_TAKEN + RESERVES_RELEASED + PAYMENT + PAYMENT_RETURNED + ADVANCE + ADVANCE_RETURN + VAT_AMOUNT + WHT_AMOUNT + VAT_AMOUNT_RETURN + WHT_AMOUNT_RETURN + ROYALTY_REVERSALS + ROYALTY_CORRECTIONS + CUSTOM_PAYMENT", "DELTA (= EST_CLOSING_BAL - LEDGER_BAL) should equal 0 when reconciled", "PAYABLE_AMOUNT sums only POSITIVE contract-level balances - negative contract balances do NOT reduce the account payable" ], "gotchas": [ "Revenue for paythrough contracts flows through adjustments, NOT this balance view - check is_paythrough_contract flag", "OPENING_BAL carries forward from previous period's LEDGER_BAL" ], "examples": [ { "question": "Current balances for account 123", "query": "SELECT sp.statement_period_name, b.CONTRACT_NAME, b.OPENING_BAL, b.NET_REVENUE, b.APPLIED_ADJUSTMENTS, b.RESERVES_TAKEN, b.RESERVES_RELEASED, b.PAYMENT, b.ADVANCE, b.EST_CLOSING_BAL, b.LEDGER_BAL, b.DELTA, b.PAYABLE_AMOUNT FROM VW_ABACUS_BALANCES_LOOKER_V2 b JOIN STATEMENT_PERIOD sp ON sp.statement_period_id = b.STATEMENT_PERIOD_ID WHERE b.ACCOUNT_ID = :account_id ORDER BY b.STATEMENT_PERIOD_ID DESC LIMIT 20", "variables": { "account_id": "123" } } ] }, { "terms": [ "ledger entry", "ledger record", "posted transaction", "ledger account contract" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.LEDGER_ACCOUNT_CONTRACT", "ROYALTY_ACCOUNTING.{{env}}.LEDGER_ACCOUNT_CONTRACT_CURRENT_BALANCE" ], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "context": "The ledger_account_contract table is the source of truth for all financial balances in Abacus. It is INSERT-only - financial data must never be updated or deleted. A positive entry is a credit (The Orchard owes the account), a negative entry is a debit (the account owes The Orchard). Key columns: ledger_account_id (PK), account_id, contract_id, currency_code, currency_amount, previous_balance, current_balance, abacus_event_id (links to the triggering event with statement_period_id and event_name). The ledger_account_contract_current_balance table (updated via DB trigger) provides the most recent entry and current balance per contract. Entry order matters - each entry records previous_balance and current_balance as running totals.", "domain": "ledger", "priority": 2, "relationships": [ "LEDGER_ACCOUNT_CONTRACT -> ACCOUNT (N:1, via account_id)", "LEDGER_ACCOUNT_CONTRACT -> CONTRACT (N:1, via contract_id)", "LEDGER_ACCOUNT_CONTRACT -> ABACUS_EVENT (N:1, via abacus_event_id, links to statement_period + event_name)", "LEDGER_ACCOUNT_CONTRACT_CURRENT_BALANCE -> LEDGER_ACCOUNT_CONTRACT (latest entry per contract, maintained by DB trigger)" ], "businessRules": [ "INSERT-only table - financial data is never updated or deleted", "Positive = credit (Orchard owes account), Negative = debit (deduction from account)", "Each entry records previous_balance and current_balance as running totals" ], "examples": [ { "question": "Recent ledger entries for account 123", "query": "SELECT c.contract_name, c.current_balance, c.account_id FROM VW_DIM_ABACUS_CONTRACT c WHERE c.account_id = :account_id ORDER BY c.contract_id", "variables": { "account_id": "123" } } ] }, { "terms": ["ledger summary", "ledger by period", "financial summary"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.LEDGER_SUMMARY_DBT"], "related": ["ROYALTY_ACCOUNTING.{{env}}.LEDGER_ACCOUNTING_RUN_BALANCE"], "context": "Ledger data aggregated by statement period combining Abacus accounting run balances and corrections. UNION of two sources: abacus_ledger (from ledger_accounting_run_balance where run_status = 'Committed') and corrections (from ledger_correction). Key columns: account_id, contract_id, statement_period_id, currency_code, total_gross_revenue_amount, total_net_revenue_amount, distribution_fee, mechanical_deduction_total, mechanical_deduction_admin_fee_total. Clustered by (account_id, contract_id, statement_period_id). Incremental append strategy with unique key [account_id, contract_id, statement_period_id].", "domain": "ledger", "priority": 2, "examples": [ { "question": "Ledger summary by statement period for account 123", "query": "SELECT statement_period_id, currency_code, SUM(total_gross_revenue_amount) AS gross_revenue, SUM(total_net_revenue_amount) AS net_revenue, SUM(distribution_fee) AS dist_fee, SUM(mechanical_deduction_total) AS mech_deduction FROM LEDGER_SUMMARY_DBT WHERE account_id = :account_id GROUP BY statement_period_id, currency_code ORDER BY statement_period_id DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "reserve", "reserves", "holdback", "reserve release", "reserve schedule" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT"], "context": "Reserves are amounts withheld from vendor balances as holdbacks against potential returns or chargebacks. Reserve tables are ledger tables (INSERT-only, never updated). RESERVES_TAKEN is the amount withheld (typically negative impact on balance). RESERVES_RELEASED is previously taken reserves returned to spendable balance. Reserves follow an installment-based release schedule via ledger_reserve_release_schedule, where installment_amount portions are released over future statement periods. Early release (liquidation) is done by inserting reversal rows that zero out future installments and creating a single new installment for the current period. Contract-level reserve configuration is in contract_reserve. Events: take_reserves (from accounting run), release_reserves (user action or scheduled).", "domain": "accounting", "priority": 2, "examples": [ { "question": "Reserve activity for account 123 by period", "query": "SELECT STATEMENT_PERIOD_ID, CONTRACT_NAME, RESERVES_TAKEN, RESERVES_RELEASED, (RESERVES_TAKEN + RESERVES_RELEASED) AS net_reserve_impact FROM VW_ABACUS_BALANCES_LOOKER_V2 WHERE ACCOUNT_ID = :account_id AND (RESERVES_TAKEN != 0 OR RESERVES_RELEASED != 0) ORDER BY STATEMENT_PERIOD_ID DESC LIMIT 20", "variables": { "account_id": "123" } } ] }, { "terms": [ "worksheet adjustment", "adjustment upload", "pending adjustment" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_ADJUSTMENTS_V2"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADJUSTMENTS_DBT", "ROYALTY_ACCOUNTING.{{env}}.REFERENCE_ADJUSTMENT_TYPE" ], "context": "Worksheet adjustments are manual balance adjustments that follow a three-stage lifecycle: (1) Uploaded/Not Approved (status_rank=1) - file uploaded, pending review; (2) Approved (status_rank=2) - approved but not yet applied to ledger; (3) Applied (status_rank=3) - committed to ledger_account_contract. VW_ABACUS_ADJUSTMENTS_V2 is the primary adjustment view with columns: batch_id, adjustment_item_id, account_id, contract_id, adjustment_amount, adjustment_currency_code, adjustment_amount_payee_currency, adjustment_type_id, oa_category_name, type_name, ledger_status, activity_period, statement_period, adjustment_comment, internal_note, approved_by, date_approved, applied_by, date_applied, apply_to_flowthrough (flag for flowthrough payment tracking). Income adjustment type IDs: 95, 17, 110, 70, 96, 66, 89, 60, 59, 54, 55, 1, 18, 103, 53, 90, 2, 88, 86, 19, 111, 109, 20, 67, 69, 68, 6. All others are expense adjustments. Type ID 65 is used to separate expenses from adjustments in dbt models. Cross-account transfers require separate adjustment rows per account - a debit row on the source account and a credit row on the destination account, potentially in different currencies (e.g., GBP debit on account A, USD credit on account B). Each row must reference the correct contract and statement period.", "domain": "adjustments", "priority": 2, "relationships": [ "VW_ABACUS_ADJUSTMENTS_V2 -> ACCOUNT (N:1, via account_id)", "VW_ABACUS_ADJUSTMENTS_V2 -> CONTRACT (N:1, via contract_id)", "VW_ABACUS_ADJUSTMENTS_V2 -> REFERENCE_ADJUSTMENT_TYPE (N:1, via adjustment_type_id)", "VW_ABACUS_ADJUSTMENTS_V2 -> STATEMENT_PERIOD (N:1, via statement_period)" ], "businessRules": [ "Lifecycle: uploaded/not_approved (status_rank=1) -> approved (status_rank=2) -> applied to ledger (status_rank=3)", "Income adjustment type IDs: 95, 17, 110, 70, 96, 66, 89, 60, 59, 54, 55, 1, 18, 103, 53, 90, 2, 88, 86, 19, 111, 109, 20, 67, 69, 68, 6 - all others are expense", "Cross-account transfers require separate debit/credit rows per account, potentially in different currencies" ], "gotchas": [ "apply_to_flowthrough flag must be set for flowthrough-related adjustments", "Type ID 65 is used to separate expenses from adjustments in dbt models" ], "examples": [ { "question": "Pending and approved adjustments for account 123", "query": "SELECT adjustment_item_id, contract_id, adjustment_amount_payee_currency, adjustment_payee_currency_code, type_name, oa_category_name, ledger_status, statement_period, activity_period, adjustment_comment FROM VW_ABACUS_ADJUSTMENTS_V2 WHERE account_id = :account_id AND ledger_status IN ('Approved', 'Not Approved') ORDER BY statement_period DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "sales", "sales data", "sales fact", "distribution sales", "royalty sales", "distro sales", "how much did we earn", "what did we earn" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_FACT_SALES", "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_FACT_SALES_DISTRO_V3", "ROYALTY_ACCOUNTING.{{env}}.ABACUS_FACT_SALES_UNIFIED_DBT" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.REVENUE_DISTRO_DBT", "ROYALTY_ACCOUNTING.{{env}}.STMT_DB_SALES_DISTRO", "FACTS.{{env}}.FACT_SALES" ], "context": "Core sales fact views for distribution royalties with transaction-level detail. ABACUS_FACT_SALES_UNIFIED_DBT merges Abacus and Workstation sales data into a single table. Key columns: statement_period_id, account_id, contract_id, account_payee_currency, sale_currency_code, sale_activity_rate, country_id, isrc, track_id, cd_id (product), store_id, upc, label_id, quantity, transaction_type, transaction_subtype, start_date. Revenue columns in both sale and payee currency: unit_price, gross_revenue, gross_revenue_after_withholding_tax, net_share (gross x royalty_rate), distribution_fee, withholding_tax, mechanical_royalty_amount, mechanical_deduction_amount, publisher_admin_fee, net_revenue_after_mechanical. VW_ABACUS_FACT_SALES_DISTRO_V3 is the primary Abacus-only view. FACT_SALES is the raw fact table in the FACTS database. REVENUE_DISTRO_DBT is the base distribution revenue detail table built from abacus_fact_sales_unified_dbt; it is the source for all REVENUE_BY_*_DBT aggregation models. Clustered by (statement_period_id, account_id, contract_id).", "domain": "sales", "priority": 2, "relationships": [ "FACT_SALES -> STATEMENT_PERIOD (N:1, via statement_period_id)", "FACT_SALES -> ACCOUNT (N:1, via account_id)", "FACT_SALES -> CONTRACT (N:1, via contract_id)", "FACT_SALES -> DIM_COUNTRY (N:1, via country_id)", "FACT_SALES -> DIM_TRACK (N:1, via track_id / isrc)", "FACT_SALES -> DIM_STORE (N:1, via store_id, join to customer_master_master for store_name)", "FACT_SALES -> DIM_ARTIST (N:1, via artist_id from joined dim tables)", "FACT_SALES -> releases (N:1, via upc to oar_art_relations.releases)" ], "businessRules": [ "Clustered by (statement_period_id, account_id, contract_id) - always filter by these for performance", "ABACUS_FACT_SALES_UNIFIED_DBT merges Abacus and Workstation data; REVENUE_DISTRO_DBT is the base for all REVENUE_BY_* aggregation models" ], "examples": [ { "question": "Sales summary for account 123 in the latest period", "query": "SELECT statement_period_id, COUNT(*) AS txn_count, SUM(quantity) AS total_quantity, SUM(gross_revenue_payee_currency) AS gross_revenue, SUM(net_share_payee_currency) AS net_share FROM ABACUS_FACT_SALES_UNIFIED_DBT WHERE account_id = :account_id AND statement_period_id = :statement_period_id GROUP BY statement_period_id", "variables": { "account_id": "123", "statement_period_id": "316" } } ] }, { "terms": [ "nr sales", "neighbouring rights sales", "performance rights sales", "nr", "knr", "ppl", "prs", "gema", "ascap", "collecting society", "cmo" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_FACT_SALES_NR_V3"], "related": [ "ROYALTY_ACCOUNTING.{{env}}.STMT_DB_SALES_NR", "FACTS.{{env}}.PERFORMANCE_NR_SOUND_RECORDING" ], "context": "Sales fact views for neighbouring rights (NR) royalties with contribution-level detail. NR sales differ from distribution sales in that they track performance rights royalties collected from CMOs (Collective Management Organizations) such as PPL (UK), PRS (UK), GEMA (Germany), ASCAP (US), BMI (US), and SESAC (US) for public performance and broadcast use. Key NR-specific columns: sound_recording_id, contributor_id, contributor_name. Revenue columns include withholding_tax (WHT pass-through from CMO). The royalty_rate comes from contract_term_condition as Number(5,4). REVENUE_NR_DBT is the transformed NR revenue base table built incrementally by txn_id.", "domain": "sales", "priority": 2, "examples": [ { "question": "NR sales by contributor for account 123", "query": "SELECT contributor_name, SUM(gross_revenue_payee_currency) AS gross_revenue, SUM(net_share_payee_currency) AS net_share, SUM(withholding_tax_payee_currency) AS withholding_tax FROM VW_ABACUS_FACT_SALES_NR_V3 WHERE account_id = :account_id AND statement_period_id = :statement_period_id GROUP BY contributor_name ORDER BY net_share DESC LIMIT 20", "variables": { "account_id": "123", "statement_period_id": "316" } } ] }, { "terms": [ "revenue", "revenue by country", "sales by territory", "earnings", "country revenue" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_REVENUE_BY_COUNTRY", "ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_COUNTRY_DBT" ], "context": "Revenue breakdown by country/territory from royalty accounting. REVENUE_BY_COUNTRY_DBT is a dbt model that UNIONs distribution revenue (revenue_distro_dbt) and NR revenue (revenue_nr_dbt), then JOINs to DIM_COUNTRY for country_code. Columns: account_id, contract_id, statement_period_id, country_code, net_revenue_payee_currency, gross_revenue_payee_currency. Clustered by (account_id, contract_id, statement_period_id, country_code). This is one of the largest dbt tables (~2B rows) using merge strategy with heavy auto-clustering costs.", "domain": "revenue", "priority": 2, "relationships": [ "REVENUE_BY_COUNTRY_DBT -> DIM_COUNTRY (N:1, via country_code for COUNTRYNAME)", "REVENUE_BY_COUNTRY_DBT -> STATEMENT_PERIOD (N:1, via statement_period_id)", "REVENUE_BY_COUNTRY_DBT built from UNION of revenue_distro_dbt + revenue_nr_dbt" ], "gotchas": [ "~2B rows - always filter by account_id and statement_period_id for performance", "JOIN to DIM_COUNTRY on country_code for human-readable country names" ], "examples": [ { "question": "Revenue by country for account 123", "query": "SELECT dc.COUNTRYNAME, r.country_code, SUM(r.net_revenue_payee_currency) AS net_revenue, SUM(r.gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_COUNTRY_DBT r JOIN DIM_COUNTRY dc ON dc.COUNTRY_CODE = r.country_code WHERE r.account_id = :account_id GROUP BY dc.COUNTRYNAME, r.country_code ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by product", "product revenue", "album revenue", "release revenue" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_REVENUE_BY_PRODUCT", "ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_PRODUCT_DISTRO_DBT" ], "context": "Revenue aggregated by product/release (album, single, EP). REVENUE_BY_PRODUCT_DISTRO_DBT is built from revenue_distro_dbt, joined to oar_art_relations.releases (on upc) and dim_artist. Key columns: account_id, contract_id, statement_period_id, product_id, product_name, release_date, display_upc, product_code, artist_id, artist_name, net_revenue_payee_currency, gross_revenue_payee_currency, mechanical_deduction_amount_payee_currency, publisher_admin_fee_payee_currency (COALESCE to 0.0). Deduplicates releases using ROW_NUMBER() OVER (PARTITION BY upc, product_type, labelid).", "domain": "revenue", "priority": 2, "examples": [ { "question": "Top 20 products by revenue for account 123", "query": "SELECT product_name, display_upc, artist_name, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_PRODUCT_DISTRO_DBT WHERE account_id = :account_id GROUP BY product_name, display_upc, artist_name ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": ["revenue by recording", "recording revenue", "isrc revenue"], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_REVENUE_BY_RECORDING", "ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_RECORDING_DISTRO_DBT", "ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_RECORDING_NR_DBT" ], "context": "Revenue aggregated by sound recording/track at the ISRC level. Separate dbt models for distribution and NR. REVENUE_BY_RECORDING_DISTRO_DBT: built from revenue_distro_dbt joined to dim_track (verified via oar_art_relations.track join). Columns: recording_id (track_unique_id), recording_title, artist, isrc, version (NULLIF TRIM for empty strings). REVENUE_BY_RECORDING_NR_DBT: built from revenue_nr_dbt joined to PERFORMANCE_NR_SOUND_RECORDING. Columns: recording_id, recording_title, main_artist (aliased as artist), isrc, version.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue by recording for account 123", "query": "SELECT recording_title, isrc, artist, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_RECORDING_DISTRO_DBT WHERE account_id = :account_id GROUP BY recording_title, isrc, artist ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by store", "dsp revenue", "platform revenue", "store revenue" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_REVENUE_BY_STORE", "ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_STORE_DBT" ], "context": "Revenue aggregated by digital service provider/store (Spotify, Apple Music, YouTube, Amazon, etc.). REVENUE_BY_STORE_DBT UNIONs distribution and NR revenue, then JOINs to customer_master_master for store_name using COLLATE('en-ci') for case-insensitive matching. Columns: account_id, contract_id, statement_period_id, store_id, store_name, net_revenue_payee_currency, gross_revenue_payee_currency.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue by store for account 123", "query": "SELECT store_name, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_STORE_DBT WHERE account_id = :account_id GROUP BY store_name ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by track", "track earnings", "song revenue", "track revenue" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_TRACK_DBT"], "context": "Distribution revenue aggregated by track. Built from revenue_distro_dbt, joined to a verified dim_track (validated via oar_art_relations.track join), dim_artist, and oar_art_relations.releases. Columns: account_id, contract_id, statement_period_id, track_unique_id, track_id, track_name, isrc, artist_id, artist_name, product_name, release_date, net_revenue_payee_currency, gross_revenue_payee_currency, mechanical_deduction_amount_payee_currency, publisher_admin_fee_payee_currency (COALESCE to 0.0).", "domain": "revenue", "priority": 2, "examples": [ { "question": "Top tracks by revenue for account 123", "query": "SELECT track_name, isrc, artist_name, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_TRACK_DBT WHERE account_id = :account_id GROUP BY track_name, isrc, artist_name ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": ["revenue by artist", "artist revenue", "artist earnings"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_ARTIST_DBT"], "context": "Revenue aggregated by artist from distribution sources. Built from revenue_distro_dbt INNER JOIN dim_artist. Columns: account_id, contract_id, statement_period_id, artist_id, artist_name, net_revenue_payee_currency (aliased from net_share), gross_revenue_payee_currency, mechanical_deduction_amount_payee_currency, publisher_admin_fee_payee_currency (COALESCE to 0.0).", "domain": "revenue", "priority": 2, "examples": [ { "question": "Top 20 artists by net revenue for account 123", "query": "SELECT artist_name, artist_id, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_ARTIST_DBT WHERE account_id = :account_id GROUP BY artist_name, artist_id ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": ["revenue by imprint", "label revenue", "imprint revenue"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_IMPRINT_DBT"], "context": "Revenue aggregated by imprint/sub-label from distribution sources. Built from revenue_distro_dbt, joined to dim_release (on upc) and dim_imprint. Columns: account_id, contract_id, statement_period_id, imprintid (as imprint_id), imprint (as imprint_name), net_revenue_payee_currency, gross_revenue_payee_currency, mechanical_deduction_amount_payee_currency, publisher_admin_fee_payee_currency (COALESCE to 0.0).", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue by imprint for account 123", "query": "SELECT imprint, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_IMPRINT_DBT WHERE account_id = :account_id GROUP BY imprint ORDER BY net_revenue DESC LIMIT 20", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by transaction type", "stream revenue", "download revenue", "revenue type breakdown" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_TRANSACTION_TYPE_DBT"], "context": "Revenue aggregated by transaction type (streams, downloads, physical, ringtones, etc.) from both distribution and NR sources. UNIONs revenue_distro_dbt and revenue_nr_dbt, then JOINs to reference_transaction_type and reference_transaction_type_group for category grouping. Columns: account_id, contract_id, statement_period_id, transaction_type_id, transaction_type_desc, transaction_type_code, transaction_type_group_id, transaction_type_group_name, quantity, net_revenue_payee_currency, gross_revenue_payee_currency.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue breakdown by transaction type for account 123", "query": "SELECT transaction_type_group_name, transaction_type_desc, SUM(quantity) AS total_quantity, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_TRANSACTION_TYPE_DBT WHERE account_id = :account_id GROUP BY transaction_type_group_name, transaction_type_desc ORDER BY net_revenue DESC", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by statement period", "period revenue", "quarterly revenue", "revenue trend by period" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_STATEMENT_PERIOD_DBT"], "context": "Revenue aggregated by statement period for trend analysis across accounting cycles. UNIONs distribution and NR revenue. JOINs to statement_period for statement_period_name and statement_period_status. Generates a primary_key hash: MD5(account_id || artist_id || contract_id || statement_period_id). Columns: account_id, contract_id, statement_period_id, statement_period_name, statement_period_status, artist_id, net_revenue_payee_currency, gross_revenue_payee_currency.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue trend by statement period for account 123", "query": "SELECT statement_period_id, statement_period_name, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_STATEMENT_PERIOD_DBT WHERE account_id = :account_id GROUP BY statement_period_id, statement_period_name ORDER BY statement_period_id DESC LIMIT 12", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by activity month", "monthly revenue", "revenue trend" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_ACTIVITY_MONTH_DBT"], "context": "Revenue aggregated by activity month - the month when the revenue-generating activity (stream, download, etc.) actually occurred, as opposed to the statement period when it was reported. Built from revenue_distro_dbt grouped by activity_period_id, joined to statement_period for activity_month_name. Columns: account_id, contract_id, statement_period_id, activity_period_id, activity_month_name, artist_id, net_revenue_payee_currency, gross_revenue_payee_currency.", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue by activity month for account 123", "query": "SELECT activity_month_name, activity_period_id, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_ACTIVITY_MONTH_DBT WHERE account_id = :account_id GROUP BY activity_month_name, activity_period_id ORDER BY activity_period_id DESC LIMIT 12", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "revenue by subaccount", "subaccount revenue", "sub-account earnings", "subaccount split", "subaccount percentage" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_SUBACCOUNT_DBT"], "context": "Revenue aggregated by subaccount (vendor account subdivisions). Built from revenue_distro_dbt joined to oar_art_relations.subaccount. Columns: account_id, contract_id, statement_period_id, subaccount_id, subaccount_name, net_revenue_payee_currency, gross_revenue_payee_currency, mechanical_deduction_amount_payee_currency, publisher_admin_fee_payee_currency (COALESCE to 0.0).", "domain": "revenue", "priority": 2, "examples": [ { "question": "Revenue by subaccount for account 123", "query": "SELECT subaccount_name, subaccount_id, SUM(net_revenue_payee_currency) AS net_revenue, SUM(gross_revenue_payee_currency) AS gross_revenue FROM REVENUE_BY_SUBACCOUNT_DBT WHERE account_id = :account_id GROUP BY subaccount_name, subaccount_id ORDER BY net_revenue DESC", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "expense", "account expense", "expenses by artist", "expenses by imprint" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.COMBINED_EXPENSES_DBT", "ROYALTY_ACCOUNTING.{{env}}.COMBINED_EXPENSES_BY_ARTIST_DBT", "ROYALTY_ACCOUNTING.{{env}}.COMBINED_EXPENSES_BY_IMPRINT_DBT", "ROYALTY_ACCOUNTING.{{env}}.EXPENSES_BY_SUBACCOUNT_DBT" ], "context": "Combined expenses from Abacus and Workstation systems. COMBINED_EXPENSES_DBT UNIONs two branches: (1) Abacus expenses from worksheet_adjustment_detail joined with reference_adjustment_type where type is expense (reference_adjustment_type_id = 65), ledger_adjustment_detail_applied, dim_release, dim_artist, subaccount; (2) Workstation expenses from release_manual_adjustment with currency conversion via exchange_rates. Key columns: account_id, contract_id, activity_statement_period_id, apply_to_statement_period_id, artist_id, subaccount_id, upc, reference_adjustment_type_id, reference_adjustment_type_name, adjustment_amount_payee_currency, adjustment_payee_currency_code. BY_ARTIST and BY_IMPRINT aggregate expenses with SUM(adjustment_amount_payee_currency). Clustered by (account_id, contract_id, apply_to_statement_period_id).", "domain": "expenses", "priority": 2, "examples": [ { "question": "Expenses by type for account 123", "query": "SELECT reference_adjustment_type_name, SUM(adjustment_amount_payee_currency) AS total_amount, adjustment_payee_currency_code FROM COMBINED_EXPENSES_DBT WHERE account_id = :account_id GROUP BY reference_adjustment_type_name, adjustment_payee_currency_code ORDER BY total_amount DESC", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "adjustment", "royalty adjustment", "correction", "adjustment by type", "manual adjustment" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADJUSTMENTS_DBT", "ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADJUSTMENTS_BY_TYPE_DBT" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_ADJUSTMENTS_V2", "ROYALTY_ACCOUNTING.{{env}}.REFERENCE_ADJUSTMENT_TYPE", "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_MANUAL_ADJUSTMENT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT" ], "context": "Combined adjustments from Abacus and Workstation systems excluding expenses (reference_adjustment_type_id != 65). COMBINED_ADJUSTMENTS_DBT UNIONs: (1) Abacus adjustments from worksheet_adjustment joined with reference_adjustment_type and ledger_adjustment_applied; (2) Workstation adjustments from manual_adjustment with currency conversion (CASE WHEN category_id IN (68, 69) THEN original_currency ELSE payee_currency). BY_TYPE aggregates by reference_adjustment_type_id/name. Key columns: account_id, contract_id, activity_statement_period_id, apply_to_statement_period_id, reference_adjustment_type_id, reference_adjustment_type_name, adjustment_amount_payee_currency. Manual adjustments (VW_ABACUS_MANUAL_ADJUSTMENT) are ad-hoc corrections; release-level adjustments target specific products.", "domain": "adjustments", "priority": 2, "examples": [ { "question": "Adjustments by type for account 123", "query": "SELECT reference_adjustment_type_name, SUM(adjustment_amount_payee_currency) AS total_amount FROM COMBINED_ADJUSTMENTS_BY_TYPE_DBT WHERE account_id = :account_id GROUP BY reference_adjustment_type_name ORDER BY total_amount DESC", "variables": { "account_id": "123" } } ] }, { "terms": ["advance", "contract advance", "advance recoupment"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADVANCES_DBT"], "related": ["ROYALTY_ACCOUNTING.{{env}}.CONTRACT_ADVANCE"], "context": "Combined advance payments from Abacus and Workstation. Advances are payments disbursed to vendors ahead of earned royalties, which are then recouped from future earnings. Key columns: account_id, contract_id, contract_advance_id, advance_description, advance_status, amount, currency_code, milestone, milestone_description, milestone_date, note. Advance status lifecycle: not_qualified -> qualified -> in_review -> approved -> pending_payment -> paid (can be deleted at any stage). Milestone types: contract_execution, delivery, recoupment, scheduled_installment, sales_milestone, option, fund_contingent, fund_non_contingent. milestone_date being NULL means the milestone hasn't been reached and the advance cannot be paid. Financial columns: amount, amount_after_withholding_and_vat (= amount + vat_amount + withholding_tax_amount), advance_amount_payee_currency, us_source_income_rate. Ledger events: confirm_advance_payment, commit_advance_payment, return_advance_payment.", "domain": "advances", "priority": 2, "relationships": [ "CONTRACT_ADVANCE -> CONTRACT (N:1, via contract_id)", "CONTRACT_ADVANCE -> ACCOUNT (N:1, via account_id)", "CONTRACT_ADVANCE -> ABACUS_EVENT (N:1, via ledger events: confirm_advance_payment, commit_advance_payment, return_advance_payment)" ], "businessRules": [ "Advance status lifecycle: not_qualified -> qualified -> approved -> paid (can be deleted at any stage)", "milestone_date being NULL means milestone not reached and advance cannot be paid", "amount_after_withholding_and_vat = amount + vat_amount + withholding_tax_amount" ], "gotchas": [ "Withholding tax and VAT on advances are calculated per country of tax residence and treaty status, not per advance", "Exchange rates are locked at advance creation time" ], "examples": [ { "question": "Advances for account 123", "query": "SELECT contract_id, advance_description, advance_status, amount, currency_code, milestone FROM COMBINED_ADVANCES_DBT WHERE account_id = :account_id ORDER BY contract_id", "variables": { "account_id": "123" } } ] }, { "terms": [ "payment data", "payment records", "payment history", "credits" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.COMBINED_PAYMENTS_DBT", "ROYALTY_ACCOUNTING.{{env}}.PAYMENTS_DBT" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.PAYMENT_GROUP_PAYMENT", "ROYALTY_ACCOUNTING.{{env}}.PAYMENT_GROUP_PAYMENT_ACCOUNT" ], "context": "Combined payments and credits from Abacus and Workstation. COMBINED_PAYMENTS_DBT UNIONs three sources: (1) Abacus payments from ledger_account_contract via abacus_event (event_name IN send_payments, commit_batch_payment, commit_custom_payment) joined to payment_group_payment and abacus_state for action_status; (2) Credit payments from ledger_account_contract with return events (payment_returned, return_withholding_tax, return_vat_summary, return_batch_payment); (3) Workstation payments from workstation_summary_dbt (payments * -1). Key columns: account_id, contract_id, statement_period_id, event_name, action_status, currency_code, currency_amount, withholding_tax_currency_amount, created_at. Unique keys: 'AB_' || ledger_account_contract_id for Abacus, 'WS_' || MD5 hash for Workstation. Clustered by (account_id, contract_id, statement_period_id).", "domain": "payments", "priority": 2, "relationships": [ "COMBINED_PAYMENTS_DBT -> ACCOUNT (N:1, via account_id)", "COMBINED_PAYMENTS_DBT -> CONTRACT (N:1, via contract_id)", "COMBINED_PAYMENTS_DBT -> STATEMENT_PERIOD (N:1, via statement_period_id)", "COMBINED_PAYMENTS_DBT -> PAYMENT_GROUP_PAYMENT (N:1, joined via abacus_event for Abacus payments)" ], "businessRules": [ "Three payment sources UNIONed: Abacus send/batch/custom payments, credit/return events, and Workstation payments", "Clustered by (account_id, contract_id, statement_period_id) - always filter by these" ], "gotchas": [ "Workstation payments are multiplied by -1 to match Abacus sign convention", "Unique keys use 'AB_' prefix for Abacus and 'WS_' + MD5 hash for Workstation records" ], "examples": [ { "question": "Payment history for account 123", "query": "SELECT statement_period_id, event_name, action_status, currency_code, SUM(currency_amount) AS total_amount FROM COMBINED_PAYMENTS_DBT WHERE account_id = :account_id GROUP BY statement_period_id, event_name, action_status, currency_code ORDER BY statement_period_id DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "flowthrough", "flow through", "automated flowthrough", "paythrough", "pay through", "pending flowthrough", "pending flowthrough payment", "ft", "ftp", "pay through contract", "pay through contracts", "paythrough contract", "paythrough contracts" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_AUTOMATED_FLOWTHROUGH" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.VW_TEMP_FLOWTHROUGH_ADJUSTMENT_TYPES" ], "context": "Automated flowthrough payment calculations. Flowthrough contracts automatically pass a percentage of revenue to a sibling contract. Four calculation formulas based on reference_flowthrough_calculation_id: (1) (Net Revenue x Rate) + Expenses - apply rate to net revenue, then add expenses; (2) (Net Revenue + Expenses) x Rate - add expenses to net revenue, then apply rate; (3) Net Revenue x Rate - standard net revenue without mechanical adjustments; (4) Gross Revenue x Rate - apply rate to gross revenue. When flowthrough_rate = 0, it defaults to 100%. Active flowthrough contracts are identified by contract_flowthrough_id IS NOT NULL AND flowthrough_status = 'active', or by contract names containing 'paythrough', 'flowthrough', or 'pay through'. Flowthrough adjustments tracked separately in balance view with three levels: PROJECTED_FLOWTHROUGH_APPLIED, PROJECTED_FLOWTHROUGH_APPROVED, PROJECTED_FLOWTHROUGH_PENDING. The has_automatic_shutoff flag and recoupment_cap control automatic termination. Revenue for paythrough contracts flows through adjustments (LEDGER_ADJUSTMENT_DETAIL and LEDGER_ADJUSTMENT_APPLIED tables), NOT the standard balances pipeline. If standard revenue queries return empty results for an account, check whether the contract is a paythrough - the revenue will appear in adjustment/flowthrough views instead.", "domain": "flowthrough", "priority": 2, "businessRules": [ "Four calculation formulas: (1) (Net Revenue x Rate) + Expenses, (2) (Net Revenue + Expenses) x Rate, (3) Net Revenue x Rate, (4) Gross Revenue x Rate", "When flowthrough_rate = 0, it defaults to 100%", "Flowthrough statuses: active | paused | shutoff; active = contract_flowthrough_id IS NOT NULL AND flowthrough_status = 'active'" ], "gotchas": [ "Revenue for paythrough contracts flows through LEDGER_ADJUSTMENT tables, NOT standard balances - check is_paythrough_contract", "Contract names containing 'paythrough', 'flowthrough', or 'pay through' are additional indicators", "Three flowthrough adjustment levels: PROJECTED_FLOWTHROUGH_APPLIED, _APPROVED, _PENDING" ], "examples": [ { "question": "Flowthrough configuration for account 123", "query": "SELECT c.contract_id, c.contract_name, c.contract_flowthrough_id, c.reference_flowthrough_calculation_id, c.flowthrough_rate, c.flowthrough_status, c.has_automatic_shutoff, c.recoupment_cap, c.is_paythrough_contract FROM VW_DIM_ABACUS_CONTRACT c WHERE c.account_id = :account_id AND c.contract_flowthrough_id IS NOT NULL", "variables": { "account_id": "123" } } ] }, { "terms": [ "workstation", "workstation summary", "legacy system", "workstation data" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.WORKSTATION_SUMMARY_DBT"], "context": "Workstation summary provides account-level rollup of legacy Workstation activity. Built from vw_workstation_summary (FACTS schema), joined to first_contract (MIN contract_id per account) and vendor_first_statement_period. Key columns: account_id, contract_id, account_name, statement_period_id, currency, opening_balance, payments, net_revenue, gross_revenue, fee, expenses, adjustments, advanced_paid, closing_balance, mechanicals, mechanical_fees. Workstation is the legacy royalty accounting system being replaced by Abacus. WHERE condition filters to statement_period_id >= first_statement_period for each vendor. Clustered by (account_id, statement_period_id).", "domain": "workstation", "priority": 2, "examples": [ { "question": "Workstation history for account 123", "query": "SELECT statement_period_id, opening_balance, gross_revenue, net_revenue, fee, expenses, adjustments, payments, closing_balance FROM WORKSTATION_SUMMARY_DBT WHERE account_id = :account_id ORDER BY statement_period_id DESC LIMIT 12", "variables": { "account_id": "123" } } ], "related": [] }, { "terms": [ "vendor", "vendor account", "vendor info", "account info", "account details", "account name" ], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_DIM_ABACUS_AR_VENDOR" ], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_DIM_ABACUS_AR_VENDOR_CONTRACT", "FACTS.{{env}}.DIM_VENDOR" ], "context": "Vendor master data from the Abacus accounts receivable system. In Abacus, an 'account' is the same entity as a 'vendor' in OA/Workstation/art_relations - account_id in royalty_accounting equals vendor_id in art_relations. Account creation is automated via Jenkins job -> Kafka event -> prod-workflow-awal-plus-account-creation step function -> prod-lambda-abacus-sync-account lambda. Key tables: account (account_id, account_name), account_payee (payment details), account_payment_term (currency_code, payment entity, payment minimum), account_tax_info (country_of_tax_residence). DIM_VENDOR is the dimension table for vendor lookups in FACTS. Currencies are associated with accounts, not contracts - changing currency requires zero balance and no pending activity. The owner field distinguishes Sony business units: Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR (Kobalt Neighbouring Rights), etc. Each has its own operational processes. Filter by owner to scope queries to a specific business unit.", "domain": "vendor", "priority": 2, "joins": [ { "from": "VW_DIM_ABACUS_AR_VENDOR", "to": "VW_DIM_ABACUS_AR_VENDOR_CONTRACT", "relation": "vendor_has_contracts" }, { "from": "VW_DIM_ABACUS_AR_VENDOR", "to": "DIM_VENDOR", "relation": "vendor_dimension" }, { "from": "DIM_VENDOR", "to": "VENDOR_CLOSERS", "relation": "vendor_has_closer" }, { "from": "VW_DIM_ABACUS_AR_VENDOR", "to": "VW_OA_CONTRACT", "relation": "vendor_owns_contracts" }, { "from": "VW_DIM_ABACUS_AR_VENDOR", "to": "ROYALTY_STATEMENT_DETAIL", "relation": "vendor_royalty_statements" } ], "examples": [ { "question": "Vendor details for account 123", "query": "SELECT VENDOR_ID, VENDOR_NAME, VENDOR_CURRENCY FROM VW_DIM_ABACUS_AR_VENDOR WHERE VENDOR_ID = :account_id", "variables": { "account_id": "123" } } ] }, { "terms": ["account dimension", "dim account", "abacus account"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_ACCOUNT"], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_DIM_ABACUS_AR_VENDOR", "FACTS.{{env}}.DIM_VENDOR" ], "context": "Denormalized account dimension view used extensively in Looker dashboards. VW_DIM_ABACUS_ACCOUNT joins account, account_payee, account_payment_term, and account_tax_info into a single flat view. Key columns: account_id, account_name, currency_code, payment_entity, payment_minimum, country_of_tax_residence, is_active. This view is the primary source for account-level filters and lookups in reporting queries. The owner field distinguishes Sony business units: Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR (Kobalt Neighbouring Rights), etc. Each has its own operational processes. Filter by owner to scope queries to a specific business unit.", "domain": "vendor", "priority": 2, "examples": [ { "question": "Account details for account 123", "query": "SELECT account_id, account_name, currency_code, payment_entity, payment_minimum, country_of_tax_residence, is_active FROM VW_DIM_ABACUS_ACCOUNT WHERE account_id = :account_id", "variables": { "account_id": "123" } } ] }, { "terms": ["signing entity", "payment entity", "contracting entity"], "targets": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_ACCOUNT"], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_DIM_ABACUS_AR_VENDOR", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_SIGNING_ENTITY" ], "context": "Signing entities represent the legal entities that sign contracts with vendors (e.g., 'The Orchard Enterprises Inc.', 'AWAL Digital Ltd.'). Each account is associated with a signing entity via account_payment_term. The signing entity determines which legal framework and payment terms apply. reference_signing_entity and reference_payment_entity tables contain the master list. Key columns: payment_entity, signing_entity_name.", "domain": "vendor", "priority": 1 }, { "terms": [ "closer", "closers", "sales rep", "sales closer", "account closer", "deal closer", "who closed the deal" ], "targets": ["FACTS.{{env}}.VENDOR_CLOSERS"], "related": ["FACTS.{{env}}.ORCHADMIN_USERS"], "context": "Vendor closers are the sales reps who signed/closed vendor deals. VENDOR_CLOSERS links vendors to their closer via VENDOR_ID and ORCHADMIN_USER_ID. Join to ORCHADMIN_USERS on ORCHADMIN_USER_ID = ID for the closer's name (FIRST_NAME, LAST_NAME).", "domain": "vendor", "priority": 2, "joins": [ { "from": "VENDOR_CLOSERS", "to": "ORCHADMIN_USERS", "relation": "closer_references_user" }, { "from": "VENDOR_CLOSERS", "to": "DIM_VENDOR", "relation": "closer_for_vendor" } ], "examples": [ { "question": "Who are the top closers by revenue?", "query": "SELECT ou.FIRST_NAME || ' ' || ou.LAST_NAME AS closer_name, COUNT(vc.VENDOR_ID) AS vendor_count FROM VENDOR_CLOSERS vc JOIN ORCHADMIN_USERS ou ON ou.ID = vc.ORCHADMIN_USER_ID GROUP BY closer_name ORDER BY vendor_count DESC LIMIT 20", "variables": {} } ] }, { "terms": [ "exchange rate", "currency conversion", "fx", "forex", "fx rate" ], "targets": ["FACTS.{{env}}.CURRENCY_EXCHANGE_RATES"], "related": ["FACTS.{{env}}.DIM_CURRENCY"], "context": "Period-specific currency exchange rates used during accounting runs to convert between sale currency, USD, and payee currency. Exchange rates are locked at the statement period when worksheets are created. Key columns: from_currency_code, to_currency_code, rate, statement_period_id. Used in dbt models for Workstation currency conversion (e.g., COMBINED_EXPENSES_DBT). In Abacus, currencies are associated with accounts (via account_payment_term), not contracts.", "domain": "reference-data", "priority": 2, "examples": [ { "question": "Exchange rates for USD to GBP across recent periods", "query": "SELECT statement_period_id, from_currency_code, to_currency_code, rate FROM CURRENCY_EXCHANGE_RATES WHERE from_currency_code = 'USD' AND to_currency_code = 'GBP' ORDER BY statement_period_id DESC LIMIT 12", "variables": {} } ] }, { "terms": ["migration", "migrated accounts", "migrated contracts"], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_OA_MIGRATED_ACCOUNTS_CONTRACTS_REPORT" ], "context": "Report of accounts and contracts migrated from the legacy Workstation system to Abacus. Shows migration status and timeline for vendor/contract onboarding to the new royalty accounting platform.", "domain": "migration", "priority": 1, "related": [] }, { "terms": ["unallocated sales", "nr unallocated"], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_UNALLOCATED_SALES_NR_STATEMENT_PERIOD" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_UNALLOCATED_SALES_DISTRO_STATEMENT_PERIOD" ], "context": "Unallocated neighbouring rights and distribution sales by statement period. These are sales transactions that could not be matched to any contract during the accounting run, typically due to missing ISRC mappings or contract gaps.", "domain": "neighbouring-rights", "priority": 1 }, { "terms": [ "dimension", "dimension table", "lookup table", "reference data", "brand", "company brand", "label brand", "label dimension", "record label lookup", "project dimension", "release project", "genre", "music genre", "currency", "currency dimension", "imprint", "label imprint", "sub-label", "subaccount", "sub-account", "vendor subdivision" ], "targets": [ "FACTS.{{env}}.DIM_VENDOR", "FACTS.{{env}}.DIM_COUNTRY", "FACTS.{{env}}.DIM_DAY", "FACTS.{{env}}.DIM_BRAND", "FACTS.{{env}}.DIM_LABEL", "FACTS.{{env}}.DIM_PROJECT", "FACTS.{{env}}.DIM_GENRE", "FACTS.{{env}}.DIM_CURRENCY", "FACTS.{{env}}.DIM_IMPRINT", "FACTS.{{env}}.DIM_SUBACCOUNT" ], "context": "Dimension tables provide lookup/reference data for fact tables. All dimension tables use DIM_ prefix and contain descriptive attributes joined to fact tables via _ID foreign keys. Key dimensions: DIM_VENDOR (vendors/labels), DIM_COUNTRY (territories), DIM_DAY (calendar), DIM_STORE (DSPs), DIM_TRACK (recordings), DIM_RELEASE (albums), DIM_ARTIST (performers), DIM_CURRENCY (ISO 4217 codes and names), DIM_BRAND (corporate brands - Sony, AWAL, The Orchard), DIM_LABEL (record labels with LABELID, LABELNAME - distinct from imprints), DIM_PROJECT (release project groupings), DIM_GENRE (music genre classification), DIM_IMPRINT (sub-label imprints with IMPRINTID, IMPRINT), DIM_SUBACCOUNT (vendor account subdivisions).", "domain": "dimensional-model", "priority": 2, "examples": [ { "question": "Look up vendor details by name", "query": "SELECT VENDORID, VENDORNAME FROM DIM_VENDOR WHERE VENDORNAME ILIKE '%:search_term%' LIMIT 20", "variables": { "search_term": "Sony" } } ], "related": [] }, { "terms": [ "fact table", "fact data", "transactional data", "measures", "fact revenue", "fact analytics", "fact sales" ], "targets": ["FACTS.{{env}}.FACT_ANALYTICS", "FACTS.{{env}}.FACT_REVENUE"], "related": ["FACTS.{{env}}.FACT_SALES"], "context": "Fact tables contain transactional measures (streams, revenue, downloads) joined to dimension tables via _ID foreign keys. FACT_ANALYTICS has streaming metrics. FACT_REVENUE has revenue measures. FACT_SALES is the core sales transaction fact with the most granular transaction-level data.", "domain": "dimensional-model", "priority": 2, "examples": [ { "question": "Total revenue by vendor in FACT_REVENUE", "query": "SELECT VENDORID, SUM(REVENUE) AS total_revenue FROM FACT_REVENUE GROUP BY VENDORID ORDER BY total_revenue DESC LIMIT 20", "variables": {} } ] }, { "terms": [ "date", "calendar", "date dimension", "day", "time period", "month", "quarter" ], "targets": ["FACTS.{{env}}.DIM_DAY", "FACTS.{{env}}.DIM_PERIOD"], "context": "Date/calendar dimension tables for time-based analysis. DIM_DAY is the primary calendar dimension with day/month/quarter/year hierarchies and attributes like day_of_week, is_weekend, fiscal_year. DIM_PERIOD maps period IDs to year/month combinations. Join to fact tables on date-type foreign keys.", "domain": "time", "priority": 2, "examples": [ { "question": "Date attributes for a specific date", "query": "SELECT DAY_DATE, DAY_OF_WEEK, MONTH_NAME, QUARTER, YEAR FROM DIM_DAY WHERE DAY_DATE = :date", "variables": { "date": "2025-01-15" } } ], "related": [] }, { "terms": ["store", "dsp", "digital service provider", "platform"], "targets": ["FACTS.{{env}}.DIM_STORE"], "context": "Store/DSP dimension table mapping store IDs to names. Key column: STOREID (PK), STORENAME. Common stores include Spotify, Apple Music, YouTube, Amazon Music, Deezer, Tidal, Pandora. Used in REVENUE_BY_STORE_DBT via customer_master_master join with COLLATE('en-ci') for case-insensitive matching.", "domain": "distribution", "priority": 2, "examples": [ { "question": "List all stores", "query": "SELECT STOREID, STORENAME FROM DIM_STORE ORDER BY STORENAME", "variables": {} } ], "related": [] }, { "terms": ["track", "recording", "isrc", "song", "sound recording"], "targets": ["FACTS.{{env}}.DIM_TRACK"], "related": [ "FACTS.{{env}}.DIM_RELEASE", "FACTS.{{env}}.DIM_TRACK_CLEAN_MV" ], "context": "Track/recording dimension with ISRC codes, track names, and release associations. ISRC (International Standard Recording Code) is the unique identifier for sound recordings (e.g., USAT21301804). DIM_TRACK_CLEAN_MV is a deduplicated materialized view. In dbt models, dim_track is validated by joining to oar_art_relations.track to ensure correct track_unique_id mapping. Version fields use NULLIF TRIM to normalize empty strings.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Look up a track by ISRC", "query": "SELECT TRACK_UNIQUE_ID, TRACKNAME, ISRC, ARTISTNAME FROM DIM_TRACK WHERE ISRC = :isrc", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": ["release", "album", "product", "upc"], "targets": ["FACTS.{{env}}.DIM_RELEASE"], "context": "Release/product dimension with UPC codes, release names, and format information. UPC (Universal Product Code) uniquely identifies a release/album. Key columns: RELEASEID, RELEASENAME, UPC, FORMAT (album, single, EP). In dbt models, releases are deduplicated using ROW_NUMBER() OVER (PARTITION BY upc, product_type, labelid) with rn = 1. Join to REVENUE_BY_PRODUCT_DISTRO_DBT on upc for product-level revenue.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Look up a release by UPC", "query": "SELECT RELEASEID, RELEASENAME, UPC, FORMAT FROM DIM_RELEASE WHERE UPC = :upc", "variables": { "upc": "602547462787" } } ], "related": [] }, { "terms": ["artist", "participant", "performer", "contributor"], "targets": ["FACTS.{{env}}.DIM_ARTIST"], "context": "Artist/participant dimension table with artist names and identifiers. Key columns: ARTISTID, ARTISTNAME. In NR (neighbouring rights) context, artists are referred to as contributors with contributor_id and contributor_name. Used across revenue models for artist-level aggregation via INNER JOIN dim_artist.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Search for an artist by name", "query": "SELECT ARTISTID, ARTISTNAME FROM DIM_ARTIST WHERE ARTISTNAME ILIKE '%:search_term%' LIMIT 20", "variables": { "search_term": "Drake" } } ], "related": [] }, { "terms": [ "transaction type", "stream type", "download type", "consumption type" ], "targets": ["FACTS.{{env}}.DIM_TRANSACTIONTYPE"], "context": "Transaction type dimension classifying consumption types. Transaction types include: streams, downloads, ringtones, physical sales, radio plays. In dbt models, joined via reference_transaction_type and grouped by reference_transaction_type_group for high-level categories (transaction_type_group_name). Key columns: transaction_type_id, transaction_type_code (4-char code), transaction_type_desc.", "domain": "analytics", "priority": 1, "related": [] }, { "terms": [ "country", "territory", "region", "market", "latam", "latin america", "nordics", "nordic countries", "benelux", "dach", "emea", "apac", "mena", "western europe", "eastern europe", "southeast asia", "north america", "south america", "caribbean", "sub-saharan africa", "uk", "united kingdom", "global" ], "targets": ["FACTS.{{env}}.DIM_COUNTRY"], "context": "DIM_COUNTRY contains all countries and territories with columns: country_code (ISO 2-letter), countryname, region, subregion. Common music-industry regional groupings (Americas, Europe, Asia, etc.) are available via the region/subregion hierarchy. Joined by country_code in revenue and streaming tables.", "domain": "geography", "priority": 2, "examples": [ { "question": "List all countries", "query": "SELECT COUNTRY_CODE, COUNTRYNAME FROM DIM_COUNTRY ORDER BY COUNTRYNAME", "variables": {} } ], "related": [] }, { "terms": [ "social data", "social metrics", "social followers", "spotify followers", "instagram followers", "tiktok followers", "monthly listeners", "spotify monthly listeners", "follower count", "follower trend", "gained followers", "lost followers", "follower growth", "follower delta", "fan conversion", "popularity score", "spotify popularity", "facebook followers", "youtube followers", "twitter followers", "soundcloud followers", "deezer followers", "social account", "how many followers", "listener count" ], "targets": ["FACTS.{{env}}.FACT_SOCIALS"], "related": [ "FACTS.{{env}}.FACT_SOCIALS_LATEST", "FACTS.{{env}}.FACT_DEMOGRAPHICS" ], "context": "Social metrics tables from ows-socials tracking follower counts and engagement across 8 platforms. Two tables exist: FACT_SOCIALS has the full historical daily timeseries (use for trends and comparisons over date ranges); FACT_SOCIALS_LATEST has only the most recent snapshot per platform per artist (use for current-state lookups). Key columns: chartmetric_artist_id (join key - NOT global_participant_id; resolve via globalParticipantByChartmetricId in GraphQL), platform (lowercase: 'spotify', 'deezer', 'facebook', 'instagram', 'twitter', 'youtube', 'soundcloud', 'tiktok'), account_url, followers (numeric), popularity (numeric, Spotify 0-100 score), monthly_listeners (Spotify-specific, rolling 28-day unique listeners), snapshot_date (date dimension), views (YouTube/TikTok timeseries). Fan conversion percentage is computed as followers / monthly_listeners - high conversion means fans are engaging beyond passive listening. To compare two artists' follower patterns, query FACT_SOCIALS for both chartmetric_artist_ids over the same date range. For follower gain/loss in a period, compare the first and last snapshot values using window functions (ROW_NUMBER ordered by snapshot_date). Queries use ROW_NUMBER() OVER (PARTITION BY ... ORDER BY snapshot_date DESC) with Snowflake QUALIFY for latest-per-partition without subqueries. Note: Apple Music and Shazam social data is only available via GraphQL (globalParticipant.socialAccounts), not in FACT_SOCIALS.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Spotify follower and monthly listener trend for an artist over a date range", "query": "SELECT snapshot_date, followers, monthly_listeners, popularity FROM FACT_SOCIALS WHERE chartmetric_artist_id = :cm_artist_id AND platform = 'spotify' AND snapshot_date BETWEEN :start_date AND :end_date ORDER BY snapshot_date", "variables": { "cm_artist_id": "12345", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Has an artist gained or lost Spotify followers in a given month", "query": "WITH endpoints AS (SELECT snapshot_date, followers, ROW_NUMBER() OVER (ORDER BY snapshot_date ASC) AS rn_first, ROW_NUMBER() OVER (ORDER BY snapshot_date DESC) AS rn_last FROM FACT_SOCIALS WHERE chartmetric_artist_id = :cm_artist_id AND platform = 'spotify' AND snapshot_date BETWEEN :start_date AND :end_date) SELECT MAX(CASE WHEN rn_first = 1 THEN snapshot_date END) AS first_date, MAX(CASE WHEN rn_first = 1 THEN followers END) AS first_followers, MAX(CASE WHEN rn_last = 1 THEN snapshot_date END) AS last_date, MAX(CASE WHEN rn_last = 1 THEN followers END) AS last_followers, MAX(CASE WHEN rn_last = 1 THEN followers END) - MAX(CASE WHEN rn_first = 1 THEN followers END) AS net_follower_change FROM endpoints", "variables": { "cm_artist_id": "12345", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Compare Spotify followers between two artists over a period", "query": "SELECT s.snapshot_date, s.chartmetric_artist_id, s.followers FROM FACT_SOCIALS s WHERE s.platform = 'spotify' AND s.chartmetric_artist_id IN (:cm_id_1, :cm_id_2) AND s.snapshot_date BETWEEN :start_date AND :end_date ORDER BY s.snapshot_date, s.chartmetric_artist_id", "variables": { "cm_id_1": "111", "cm_id_2": "222", "start_date": "2026-02-01", "end_date": "2026-02-28" } }, { "question": "Current follower count across all platforms for an artist", "query": "SELECT platform, followers, popularity, monthly_listeners, snapshot_date FROM FACT_SOCIALS_LATEST WHERE chartmetric_artist_id = :cm_artist_id ORDER BY followers DESC", "variables": { "cm_artist_id": "12345" } } ] }, { "terms": [ "ad spend", "advertising spend", "marketing spend", "market share", "competitive data", "competitive positioning" ], "targets": [ "FACTS.{{env}}.FACT_AD_SPEND", "FACTS.{{env}}.FACT_MARKET_SHARE" ], "related": [], "context": "FACT_AD_SPEND tracks marketing expenditure for ROI analysis against streaming performance. FACT_MARKET_SHARE has competitive positioning data showing market share by store and country. Use together to correlate ad spend with market share changes.", "domain": "analytics", "priority": 1 }, { "terms": [ "chart position", "chart ranking", "chart data", "top 200", "top 100", "viral 50", "viral 100", "viral chart", "chart entry", "chart debut", "weeks on chart", "shazam chart", "shazam", "billboard", "spotify chart", "apple music chart", "deezer chart", "amazon chart", "youtube chart", "tiktok chart", "soundcloud chart", "daily chart", "weekly chart", "chart position over time", "chart peak", "chart streak", "streak length", "what charts is this on", "chart placement", "chart trend", "chart history" ], "targets": ["FACTS.{{env}}.FACT_CHARTS"], "related": ["FACTS.{{env}}.FACT_ANALYTICS"], "context": "Chart position data across music charts. Key columns: isrc, chart_id, chart_name, position, previous_position, peak_position, position_change, weeks_on_chart, streak_length, country_code, date, store_id. CHART TYPES BY PLATFORM: Spotify - Daily Top 200 (tracks, daily, 200 entries), Weekly Top 200, Daily Viral 100; Apple Music - Daily Top 100 (tracks, daily, 100 entries per country); Deezer - Daily Top 100; Shazam - Daily Top Tracks (200); YouTube - Top Songs (weekly, 100), Top Videos (weekly, 100); Amazon - Top Tracks; TikTok - All Time Top Tracks (daily, 1000), Weekly Top Tracks (1000); SoundCloud - Daily Top Tracks (200), Daily New & Hot (200); LINE Music (Japan) - Daily/Weekly Top 100; Recochoku (Japan) - Daily/Weekly Top 200; iTunes - Daily Top Albums. For chart entry/debut analysis filter where previous_position IS NULL. For daily position history use date range filters. Note: Users often confuse playlists with charts - 'Amazon Daily Pop' is a playlist (query via playlist tables), not a chart.", "domain": "analytics", "priority": 3, "examples": [ { "question": "Chart placements for a track on Spotify Global Top 200", "query": "SELECT date, position, previous_position, peak_position FROM FACT_CHARTS WHERE isrc = :isrc AND store_id = 286 AND country_code = 'GLOBAL' ORDER BY date DESC LIMIT 30", "variables": { "isrc": "USAT21301804" } }, { "question": "Daily chart position for a track over a date range on a specific chart", "query": "SELECT date, position, previous_position, position_change FROM FACT_CHARTS WHERE isrc = :isrc AND chart_name = :chart_name AND date BETWEEN :start_date AND :end_date ORDER BY date", "variables": { "isrc": "USAT21301804", "chart_name": "Spotify Daily Top 200", "start_date": "2026-02-02", "end_date": "2026-02-05" } }, { "question": "Which charts a track appears on across all platforms", "query": "SELECT chart_name, store_id, country_code, MIN(date) AS first_entry, MIN(position) AS peak_position FROM FACT_CHARTS WHERE isrc = :isrc AND date >= DATEADD('day', -7, CURRENT_DATE()) GROUP BY chart_name, store_id, country_code ORDER BY peak_position ASC", "variables": { "isrc": "USAT21301804" } }, { "question": "What charts has a track entered in a specific date range with current positions", "query": "SELECT chart_name, country_code, position, date FROM FACT_CHARTS WHERE isrc = :isrc AND date BETWEEN :start_date AND :end_date ORDER BY date DESC, position ASC", "variables": { "isrc": "USAT21301804", "start_date": "2026-02-15", "end_date": "2026-02-18" } } ] }, { "terms": [ "nr sound recording", "performance nr", "neighbouring rights recording", "knr recording" ], "targets": ["FACTS.{{env}}.PERFORMANCE_NR_SOUND_RECORDING"], "context": "Neighbouring rights performance data at the sound recording level with contribution details. Used as a join table in REVENUE_BY_RECORDING_NR_DBT to enrich NR revenue with recording metadata (recording_id, recording_title, main_artist, isrc, version).", "domain": "neighbouring-rights", "priority": 1, "related": [] }, { "terms": ["withholding tax", "wht", "tax withholding", "vat", "tax rate"], "targets": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_ACCOUNT"], "context": "Withholding tax (WHT) and VAT amounts tracked in the Abacus ledger. WHT is deducted at source from royalty payments based on the vendor's country_of_tax_residence and applicable tax treaties. VAT is applied based on jurisdiction. Balance columns: WHT_AMOUNT (withheld), WHT_AMOUNT_RETURN (returned), VAT_AMOUNT, VAT_AMOUNT_RETURN. Tax info is stored per account in account_tax_info (country_of_tax_residence, us_source_income_rate). Ledger events: commit_withholding_tax, commit_vat, return_withholding_tax, return_vat_summary.", "domain": "accounting", "priority": 2, "examples": [ { "question": "WHT and VAT for account 123 by period", "query": "SELECT STATEMENT_PERIOD_ID, CONTRACT_NAME, WHT_AMOUNT, WHT_AMOUNT_RETURN, VAT_AMOUNT, VAT_AMOUNT_RETURN FROM VW_ABACUS_BALANCES_LOOKER_V2 WHERE ACCOUNT_ID = :account_id AND (WHT_AMOUNT != 0 OR VAT_AMOUNT != 0) ORDER BY STATEMENT_PERIOD_ID DESC LIMIT 20", "variables": { "account_id": "123" } } ] }, { "terms": [ "earnings transfer", "cross recoup", "cross-recoup", "reclass", "reclassify earnings", "transfer between contracts", "earnings override", "nr transfer" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.EARNINGS_TRANSFER"], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT"], "context": "Earnings transfers move revenue between contracts within or across accounts. Five transfer types: CROSS_RECOUP (offset losses against profits from another contract), RECLASS (reclassify earnings between categories), OVERRIDE (manual adjustment), TRANSFER (direct transfer between contracts), NR_TRANSFER (neighbouring rights transfer). Each transfer has a rate_type (FLAT_RATE or PERCENT) and input basis (CLOSING_BALANCE, GROSS_REVENUE, or NET_REVENUE). Key columns: earnings_transfer_id, source_account_id, source_contract_id, destination_account_id, destination_contract_id, transfer_type, rate_type, rate, input, statement_period_id.", "domain": "accounting", "priority": 2, "examples": [ { "question": "Cross-recoup transfers for account 123", "query": "SELECT source_contract_id, destination_contract_id, transfer_type, rate_type, rate, input FROM EARNINGS_TRANSFER WHERE source_account_id = :account_id AND transfer_type = 'CROSS_RECOUP'", "variables": { "account_id": "123" } } ] }, { "terms": [ "vat summary", "vat by period", "vat by contract", "vat totals" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.LEDGER_VAT_SUMMARY"], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "context": "Aggregated VAT amounts by statement period, account, and contract. Provides period-level VAT totals rather than per-transaction VAT details. Key columns: account_id, contract_id, statement_period_id, currency_code, vat_amount, vat_amount_return. Use for VAT reporting and reconciliation across periods.", "domain": "accounting", "priority": 1, "examples": [ { "question": "VAT summary for account 123 by period", "query": "SELECT statement_period_id, contract_id, currency_code, SUM(vat_amount) AS total_vat, SUM(vat_amount_return) AS total_vat_return FROM LEDGER_VAT_SUMMARY WHERE account_id = :account_id GROUP BY statement_period_id, contract_id, currency_code ORDER BY statement_period_id DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "reserves taken", "reserve holdback detail", "reserve deduction", "how much was held back", "reserves withheld" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.LEDGER_RESERVE_TAKEN"], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "context": "Individual reserve holdback entries recorded in the ledger. Each row represents an amount withheld from a contract's balance during an accounting run. Key columns: account_id, contract_id, statement_period_id, abacus_event_id, currency_code, currency_amount, previous_balance, current_balance. INSERT-only - reserve entries are never updated or deleted. Complements RESERVES_TAKEN in the balances view with transaction-level granularity.", "domain": "accounting", "priority": 1, "examples": [ { "question": "Reserve holdbacks for account 123 by period", "query": "SELECT statement_period_id, contract_id, currency_code, SUM(currency_amount) AS total_reserved FROM LEDGER_RESERVE_TAKEN WHERE account_id = :account_id GROUP BY statement_period_id, contract_id, currency_code ORDER BY statement_period_id DESC", "variables": { "account_id": "123" } } ] }, { "terms": [ "applied adjustment detail", "adjustment line items", "which adjustments were applied", "adjustment breakdown", "ledger adjustment detail", "ledger adjustment applied", "applied adjustments detail", "adjustment applied" ], "targets": [ "ROYALTY_ACCOUNTING.{{env}}.LEDGER_ADJUSTMENT_DETAIL", "ROYALTY_ACCOUNTING.{{env}}.LEDGER_ADJUSTMENT_APPLIED" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_ADJUSTMENTS_V2"], "context": "Granular adjustment records at the line-item level. LEDGER_ADJUSTMENT_DETAIL contains the individual adjustment rows with UPC, distribution_type, and per-line amounts. LEDGER_ADJUSTMENT_APPLIED links adjustments to the ledger entries created when they were committed. Key columns: account_id, contract_id, statement_period_id, reference_adjustment_type_id, adjustment_amount, currency_code, upc, apply_to_flowthrough. Use for detailed audit of which adjustments were applied and their line-item breakdown.", "domain": "adjustments", "priority": 2, "examples": [ { "question": "Applied adjustment details for account 123", "query": "SELECT lad.contract_id, lad.reference_adjustment_type_id, lad.upc, lad.adjustment_amount, lad.currency_code, lad.apply_to_flowthrough FROM LEDGER_ADJUSTMENT_DETAIL lad JOIN LEDGER_ADJUSTMENT_APPLIED laa ON laa.ledger_adjustment_detail_id = lad.ledger_adjustment_detail_id WHERE lad.account_id = :account_id ORDER BY lad.statement_period_id DESC LIMIT 50", "variables": { "account_id": "123" } } ] }, { "terms": [ "payment entities by period", "statement period payment entity", "which entities are paying this period" ], "targets": ["ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD_PAYMENT_ENTITY"], "related": ["ROYALTY_ACCOUNTING.{{env}}.STATEMENT_PERIOD"], "context": "Links statement periods to active payment entities. Each payment entity (e.g., The Orchard Enterprises, AWAL Digital) processes payments for specific periods. Key columns: statement_period_id, payment_entity_id, status. Use to determine which legal entities are processing payments for a given period.", "domain": "payments", "priority": 1 }, { "terms": [ "vendor dimension", "vendor lookup", "dim vendor", "vendor hierarchy", "d3 hierarchy", "parent vendor" ], "targets": [ "FACTS.{{env}}.DIM_VENDOR", "FACTS.{{env}}.DIM_VENDOR_HIERARCHY" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT"], "context": "Vendor dimension tables provide lookup/reference data for accounts (vendors). DIM_VENDOR contains the master vendor list with key columns: vendor_id (= account_id in Abacus), vendor_name, vendor_status, parent_vendor_id, owner (business unit: Orchard, AWAL-UK, AWAL-Core, AWAL-US, KNR). DIM_VENDOR_HIERARCHY maps parent-child relationships for D3 (distributor label) accounts and their sub-label accounts. Join to fact tables via vendor_id. Use parent_vendor_id to navigate the D3 -> subaccount hierarchy.", "domain": "dimensions", "priority": 2, "examples": [ { "question": "Find all subaccounts under a D3 parent", "query": "SELECT vendor_id, vendor_name, vendor_status, owner FROM DIM_VENDOR WHERE parent_vendor_id = :parent_vendor_id ORDER BY vendor_name", "variables": { "parent_vendor_id": "123" } } ] }, { "terms": [ "store dimension", "store lookup", "dim store", "customer master", "dms", "spotify", "apple music", "amazon music", "youtube music", "tidal", "deezer" ], "targets": ["FACTS.{{env}}.DIM_STORE"], "related": ["FACTS.{{env}}.FACT_SALES"], "context": "Store dimension table provides lookup data for digital service providers (DSPs) and stores. DIM_STORE contains the master store list with key columns: store_id, store_name, store_type, is_active. Stores include streaming platforms (Spotify, Apple Music, Amazon Music, YouTube Music, Tidal, Deezer), download stores, and collecting societies (PPL, GEMA, etc.). A 'Customer Master' (legacy: DMS Customer) is a store-territory combination (e.g., iTunes UK), distinct from the store alone. The store entity itself (legacy: DMS Master / Digital Master Service) is territory-independent. Store is overloaded to additionally include performance rights societies, physical distributors, and content variants (e.g., YouTube vs YouTube Art Tracks vs YouTube Subscription). Join to sales/revenue fact tables via store_id. Use to resolve store names when analyzing revenue by platform.", "domain": "dimensions", "priority": 2, "examples": [ { "question": "List all active stores", "query": "SELECT store_id, store_name, store_type FROM DIM_STORE WHERE is_active = TRUE ORDER BY store_name", "variables": {} } ] }, { "terms": [ "country dimension", "country lookup", "dim country", "territory lookup", "iso country" ], "targets": ["FACTS.{{env}}.DIM_COUNTRY"], "related": ["FACTS.{{env}}.FACT_SALES"], "context": "DIM_COUNTRY dimension table with columns: country_code (ISO 2-letter), countryname, region, subregion. Joined to FACT_ANALYTICS and revenue tables via country_code for geographic breakdowns.", "domain": "dimensions", "priority": 2, "examples": [ { "question": "List countries in a region", "query": "SELECT country_id, country_name, country_code, region, sub_region FROM DIM_COUNTRY WHERE region = :region ORDER BY country_name", "variables": { "region": "Europe" } } ] }, { "terms": [ "track dimension", "track lookup", "dim track", "isrc lookup", "song lookup" ], "targets": ["FACTS.{{env}}.DIM_TRACK"], "related": ["FACTS.{{env}}.FACT_SALES", "FACTS.{{env}}.DIM_ARTIST"], "context": "Track dimension table provides lookup data for individual tracks/sound recordings. DIM_TRACK contains the master track list with key columns: track_id, track_name, isrc, artist_id, product_id (cd_id), duration, explicit_flag. Join to sales fact tables via track_id. Use isrc for cross-system lookups between distribution and accounting.", "domain": "dimensions", "priority": 2, "examples": [ { "question": "Look up track by ISRC", "query": "SELECT track_id, track_name, isrc, artist_id FROM DIM_TRACK WHERE isrc = :isrc", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "artist dimension", "artist lookup", "dim artist", "participant lookup" ], "targets": ["FACTS.{{env}}.DIM_ARTIST"], "related": ["FACTS.{{env}}.DIM_TRACK", "FACTS.{{env}}.FACT_SALES"], "context": "Artist dimension table provides lookup data for artists/participants. DIM_ARTIST contains the master artist list with key columns: artist_id, artist_name, vendor_id. Links artists to their distributing vendor/account. Join to fact tables via artist_id or use vendor_id to find all artists under a specific account.", "domain": "dimensions", "priority": 2, "examples": [ { "question": "Find artists under vendor 123", "query": "SELECT artist_id, artist_name FROM DIM_ARTIST WHERE vendor_id = :vendor_id ORDER BY artist_name", "variables": { "vendor_id": "123" } } ] }, { "terms": [ "dim date", "date lookup", "fiscal period", "fiscal year", "fiscal quarter" ], "targets": ["FACTS.{{env}}.DIM_DATE"], "related": ["FACTS.{{env}}.FACT_SALES", "FACTS.{{env}}.DIM_DAY"], "context": "DIM_DATE is an alternative date dimension alongside DIM_DAY. Contains one row per day with columns: date_id, full_date, day_of_week, month, quarter, year, fiscal_year, fiscal_quarter. DIM_DAY is the primary calendar dimension; DIM_DATE may be preferred for joins using integer date_id keys.", "domain": "dimensions", "priority": 1 }, { "terms": [ "streams", "streaming metrics", "streams rollup", "track streams", "track performance", "streams by store", "streams by country", "streams by feed", "streaming performance", "7 day streams", "28 day streams", "all time streams", "stream count", "top tracks", "gainers", "best performing", "top performing", "highest streams", "total streams", "most streams", "top songs", "top artists by streams", "streaming leaderboard", "growth percentage", "stream growth", "apple streams", "spotify streams", "amazon streams", "youtube streams", "deezer streams", "artist streams", "artist total streams", "streams by artist" ], "targets": [ "FACTS.{{env}}.METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_TRACK_PARTICIPANT_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_PRODFAM_ROLLUP_V2" ], "related": [ "FACTS.{{env}}.METRICS_BY_PRODUCT_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_PRODUCT_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_ISRC_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_TRACK_CREATIONS_THRESHOLD_ROLLUP", "FACTS.{{env}}.METRICS_BY_ACCOUNT_28_DAYS_ROLLUP", "FACTS.{{env}}.DBT_V_METRICS_BY_MULTI_PRODUCT_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.DBT_V_METRICS_BY_TRACK_PARTICIPANT_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.DIM_FEED", "FACTS.{{env}}.DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_PRODFAM_ROLLUP", "FACTS.{{env}}.DBT_V_METRICS_BY_TRACK_REGION_FEED_DISTRIBUTOR_ROLLUP" ], "context": "Pre-aggregated streaming metrics tables from ows-analytics. Rollup tables contain bucketed stream counts (1-day, 7-day, 28-day, 183-day, 365-day, all-time) with growth percentages and previous-period comparisons, aggregated by track (ISRC), product, participant (artist), or account. Key columns: isrc, product_id, global_participant_id, feed_id (store), country_code, streams_1_day, streams_1_day_prev, streams_7_days, streams_7_days_prev, streams_28_days, streams_28_days_prev, streams_183_days, streams_365_days, streams_all_time, data_lag_in_days, min_release_date, deletions_for_isrc. Growth is computed as (current - prev) / prev. Tables exist in both legacy (e.g., METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP) and DBT-generated variants (e.g., DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP). The DBT variants add product-family and region dimensions. The CREATIONS_THRESHOLD variant powers the 'gainers' mode with columns: amazon_active_discovery_streams_*, apple_active_discovery_streams_*, spotify_active_discovery_streams_*, tiktok_views_*, tiktok_creations_*. DIM_FEED maps feed_id to store names.", "domain": "streaming", "priority": 3, "examples": [ { "question": "Top 20 tracks by 28-day streams for a label", "query": "SELECT m.isrc, t.track_name, m.streams_28_days, m.streams_7_days, m.streams_1_day FROM METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_TRACK t ON t.isrc = m.isrc WHERE m.label_id = :label_id ORDER BY m.streams_28_days DESC LIMIT 20", "variables": { "label_id": "1234" } }, { "question": "Top 10 songs with highest streams globally (all artists) - use rollup for recent windows", "query": "SELECT m.isrc, t.track_name, m.streams_7_days, m.streams_28_days, m.streams_all_time FROM METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_TRACK t ON t.isrc = m.isrc ORDER BY m.streams_7_days DESC LIMIT 10", "variables": {} }, { "question": "Best performing product for an artist on a specific DSP by all-time streams", "query": "SELECT m.product_id, r.release_name, SUM(m.streams_all_time) AS total_streams FROM METRICS_BY_PRODUCT_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_RELEASE r ON r.product_id = m.product_id WHERE m.global_participant_id = :gp_id AND m.feed_id = :feed_id GROUP BY m.product_id, r.release_name ORDER BY total_streams DESC LIMIT 10", "variables": { "gp_id": "12345", "feed_id": "187" } }, { "question": "Which DSPs contribute at least 75% of total all-time streams for a product", "query": "WITH by_store AS (SELECT f.feed_name AS store, SUM(m.streams_all_time) AS store_streams FROM METRICS_BY_PRODUCT_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_FEED f ON f.feed_id = m.feed_id WHERE m.product_id = :product_id GROUP BY f.feed_name), totals AS (SELECT SUM(store_streams) AS grand_total FROM by_store) SELECT b.store, b.store_streams, ROUND(b.store_streams / t.grand_total * 100, 2) AS pct FROM by_store b CROSS JOIN totals t WHERE b.store_streams / t.grand_total >= 0.05 ORDER BY b.store_streams DESC", "variables": { "product_id": "67890" } }, { "question": "Top tracks in a specific country by 7-day streams", "query": "SELECT m.isrc, t.track_name, m.streams_7_days, m.streams_28_days FROM DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_TRACK t ON t.isrc = m.isrc WHERE m.country_code = :country ORDER BY m.streams_7_days DESC LIMIT 10", "variables": { "country": "EE" } } ] }, { "terms": [ "daily streams", "stream timeseries", "streams over time", "daily streaming data", "stream trend", "streaming trend", "streams by day", "daily track performance" ], "targets": [ "FACTS.{{env}}.V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.V_STREAMS_BY_PRODUCT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_PRODUCT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DATA_AVAILABILITY_BY_STORE_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_PRODFAM_ROLLUP", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_PRODFAM_ROLLUP_V2" ], "context": "Daily streaming timeseries tables from ows-analytics. Contain per-day stream counts broken down by track (ISRC), feed (store), distributor, and optionally country. Tables exist in both legacy (V_STREAMS_BY_*) and DBT-generated (DBT_V_STREAMS_BY_*) variants. Key columns: isrc, product_id, global_participant_id, feed_id (store), country_code, download_activity_date (the date), distributor, streams, streams_active, streams_passive, streams_collection, skips, saves, sub_type_subscription (paid tier streams), sub_type_adsupported (free/ad-supported tier streams), sub_type_midtier (mid-tier plan streams). Plus all per-DSP SOS columns (see SOS entry). Multiple entity-level variants exist: V_STREAMS_BY_TRACK_* (by ISRC), V_STREAMS_BY_PRODUCT_TRACK_* (by product_id+ISRC), V_STREAMS_BY_PARTICIPANT_TRACK_* (by global_participant_id+ISRC), V_STREAMS_BY_ACCOUNT_TRACK_* (by account+ISRC). Country variants add country_code. Always check DATA_AVAILABILITY_BY_STORE_DAILY for the latest available date per store before querying.", "domain": "streaming", "priority": 3, "examples": [ { "question": "Daily Spotify streams for an ISRC over a date range", "query": "SELECT download_activity_date AS date, SUM(streams) AS streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date BETWEEN :start_date AND :end_date GROUP BY download_activity_date ORDER BY download_activity_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Total streams for a track by DSP/store over a date range", "query": "SELECT f.feed_name AS store_name, SUM(s.streams) AS total_streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY s JOIN DIM_FEED f ON f.feed_id = s.feed_id WHERE s.isrc = :isrc AND s.download_activity_date BETWEEN :start_date AND :end_date GROUP BY f.feed_name ORDER BY total_streams DESC", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-21", "end_date": "2026-01-28" } }, { "question": "Daily streams for a track in a specific country on a specific DSP", "query": "SELECT download_activity_date AS date, SUM(streams) AS streams FROM DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = :feed_id AND country_code = :country AND download_activity_date BETWEEN :start_date AND :end_date GROUP BY download_activity_date ORDER BY download_activity_date", "variables": { "isrc": "USAT21301804", "feed_id": "286", "country": "DE", "start_date": "2026-01-01", "end_date": "2026-12-31" } }, { "question": "Total streams for multiple tracks by an artist between dates to find best performing", "query": "SELECT s.isrc, t.track_name, SUM(s.streams) AS total_streams FROM V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY s JOIN DIM_TRACK t ON t.isrc = s.isrc WHERE s.global_participant_id = :gp_id AND s.download_activity_date BETWEEN :start_date AND :end_date GROUP BY s.isrc, t.track_name ORDER BY total_streams DESC", "variables": { "gp_id": "12345", "start_date": "2026-01-01", "end_date": "2026-01-28" } } ] }, { "terms": [ "downloads", "download count", "track downloads", "album downloads", "download metrics", "itunes downloads", "digital purchases" ], "targets": [ "FACTS.{{env}}.DOWNLOADS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DOWNLOADS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.DOWNLOADS_BY_PRODUCT_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DOWNLOADS_BY_PRODUCT_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DOWNLOADS_BY_PRODUCT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DOWNLOADS_BY_PARTICIPANT_PRODUCT_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DOWNLOADS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_DOWNLOADS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_DOWNLOADS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "context": "Daily download tables from ows-analytics. Track digital purchase/download counts by track, product, or participant, with optional country breakdown. Key columns: isrc, product_id, global_participant_id, feed_id, country_code, date, downloads, distributor_id. Separate from streaming tables - these cover paid downloads (iTunes, Amazon purchases, etc.), not streaming consumption. Multiple entity-level variants mirror the streaming tables structure.", "domain": "streaming", "priority": 1 }, { "terms": [ "demographics", "age breakdown", "gender breakdown", "listener demographics", "audience age", "audience gender", "listener profile", "who listens", "fan demographics" ], "targets": [ "FACTS.{{env}}.STREAMS_DEMOGRAPHICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_STREAMS_DEMOGRAPHICS_BY_TRACK_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.STREAMS_DEMOGRAPHICS_BY_PARTICIPANT_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_STREAMS_DEMOGRAPHICS_BY_PARTICIPANT_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.STREAMS_DEMOGRAPHICS_BY_PRODUCT_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_STREAMS_DEMOGRAPHICS_BY_PRODUCT_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.STREAMS_DEMOGRAPHICS_BY_PARTICIPANT_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_DEMOGRAPHICS_BY_PLAYLIST_COUNTRY", "FACTS.{{env}}.DBT_V_STREAMS_DEMOGRAPHICS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_DEMOGRAPHICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "context": "Demographics tables from ows-analytics. Contain age group and gender breakdowns for streaming consumption, broken down by track, participant (artist), or product. Key columns: isrc, global_participant_id, product_id, feed_id, country_code, age_group, gender, streams. Age buckets differ by platform: Apple (under_18, 18-24, 25-34, 35-44, 45-54, 55-64, 65+) vs Spotify (under_18, 18-22, 23-27, 28-34, 35-44, 45-59, 60+). Rollup tables have aggregated totals; daily tables have per-day breakdowns. V_DEMOGRAPHICS_BY_PLAYLIST_COUNTRY provides playlist-level demographics by age and gender per country.", "domain": "streaming", "priority": 2, "examples": [ { "question": "Age and gender breakdown for a track on Spotify", "query": "SELECT age_group, gender, SUM(streams) AS streams FROM STREAMS_DEMOGRAPHICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP WHERE isrc = :isrc AND feed_id = 286 GROUP BY age_group, gender ORDER BY streams DESC", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "youtube views", "video views", "video analytics", "channel views", "youtube analytics", "watch time", "average view duration", "video performance", "cpm", "rpm", "ad revenue", "youtube revenue", "video traffic sources", "ugc", "user generated content", "youtube claims" ], "targets": [ "FACTS.{{env}}.VIEWS_BY_VIDEO_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_VIEWS_BY_VIDEO_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.VIEWS_BY_CHANNEL_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.METRICS_BY_VIDEO_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_VIDEO_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.METRICS_BY_CHANNEL_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_VIEWS_BY_VIDEO_SOURCE_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.VIEWS_BY_CHANNEL_SOURCE_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_METRICS_UGC_BY_VIDEO_ASSET_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.YOUTUBE_VIDEO", "FACTS.{{env}}.MAPPINGS_VIDEO_TO_TRACKS_V3", "FACTS.{{env}}.MAPPINGS_VIDEO_TO_CHANNELS", "FACTS.{{env}}.DBT_V_VIEWS_BY_VIDEO_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_VIEWS_BY_VIDEO_SOURCE_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_VIEWS_BY_VIDEO_SOURCE_FEED_DISTRIBUTOR_DAILY" ], "context": "YouTube/video analytics tables from ows-analytics. VIEWS_BY_VIDEO_* tables contain daily view counts per video with optional country breakdown. VIEWS_BY_CHANNEL_* tables aggregate at the channel level. METRICS_BY_VIDEO/CHANNEL_* rollup tables include premium views, watch time, average view duration, CPM, RPM, ad fill rate, ad revenue, and comments. Traffic source tables (*_SOURCE_*) break down views by how viewers discovered the content. UGC tables (METRICS_UGC_BY_VIDEO_ASSET_*) track user-generated content claims with claim types and statuses. YOUTUBE_VIDEO maps video_id to metadata. MAPPINGS_VIDEO_TO_TRACKS_V3 links videos to ISRCs; MAPPINGS_VIDEO_TO_CHANNELS links videos to channels.", "domain": "video", "priority": 2, "examples": [ { "question": "Daily views for a YouTube video over the last 30 days", "query": "SELECT date, SUM(views) AS views FROM VIEWS_BY_VIDEO_FEED_DISTRIBUTOR_DAILY WHERE video_id = :video_id AND date >= DATEADD('day', -30, CURRENT_DATE()) GROUP BY date ORDER BY date", "variables": { "video_id": "dQw4w9WgXcQ" } } ] }, { "terms": [ "tiktok", "tiktok creations", "tiktok views", "tiktok analytics", "tiktok trend", "tiktok score", "tiktok viral", "ugc", "pgc", "user generated content", "professionally generated content", "tiktok likes", "tiktok ugc", "tiktok pgc", "tiktok shares", "tiktok comments", "tiktok favorites", "tiktok engagement", "tiktok performance", "how is performing on tiktok", "tiktok streams" ], "targets": [ "FACTS.{{env}}.V_TIKTOK_BY_ISRC_COUNTRY_DAILY", "FACTS.{{env}}.TIKTOK_BY_ISRC_COUNTRY_ROLLUP" ], "related": [ "FACTS.{{env}}.V_TIKTOK_BY_ISRC_PRODUCT_COUNTRY_DAILY", "FACTS.{{env}}.TIKTOK_BY_ISRC_PRODUCT_COUNTRY_ROLLUP", "FACTS.{{env}}.TIKTOK_TREND_SCORE_BY_ISRC_DBT", "FACTS.{{env}}.DBT_TIKTOK_VIDEO" ], "context": "TikTok analytics tables from ows-analytics. Full metric columns: views, creations (videos using a sound), likes, favorites, shares, comments, streams, tiktok_trend_score, content_type, country_code, isrc, date. The content_type column distinguishes UGC (user-generated content - fan videos) from PGC (professionally-generated content - official artist videos). Filter content_type = 'UGC' or 'PGC' to see the breakdown; aggregate without filtering for totals. Daily tables (V_TIKTOK_BY_ISRC_COUNTRY_DAILY, V_TIKTOK_BY_ISRC_PRODUCT_COUNTRY_DAILY) have per-day timeseries; rollup tables (TIKTOK_BY_ISRC_COUNTRY_ROLLUP, TIKTOK_BY_ISRC_PRODUCT_COUNTRY_ROLLUP) have pre-aggregated 1-day/7-day/28-day/all-time windows with columns like views_1_day, views_7_days, creations_1_day, creations_7_days, etc. TIKTOK_TREND_SCORE_BY_ISRC_DBT provides proprietary trend scoring per ISRC per country for identifying viral/trending sounds. Product-level variants add product_id for album-level aggregation.", "domain": "streaming", "priority": 3, "examples": [ { "question": "TikTok creations and views for an ISRC by country", "query": "SELECT country_code, SUM(creations) AS creations, SUM(views) AS views FROM TIKTOK_BY_ISRC_COUNTRY_ROLLUP WHERE isrc = :isrc GROUP BY country_code ORDER BY creations DESC LIMIT 20", "variables": { "isrc": "USAT21301804" } }, { "question": "TikTok likes distributed between UGC and PGC for a track over a date range", "query": "SELECT content_type, SUM(likes) AS total_likes, SUM(views) AS total_views, SUM(creations) AS total_creations, SUM(shares) AS total_shares, SUM(comments) AS total_comments FROM V_TIKTOK_BY_ISRC_COUNTRY_DAILY WHERE isrc = :isrc AND date BETWEEN :start_date AND :end_date GROUP BY content_type", "variables": { "isrc": "USAT21301804", "start_date": "2026-04-08", "end_date": "2026-04-13" } }, { "question": "Daily TikTok likes for a track over a date range", "query": "SELECT date, SUM(likes) AS likes, SUM(views) AS views, SUM(creations) AS creations FROM V_TIKTOK_BY_ISRC_COUNTRY_DAILY WHERE isrc = :isrc AND date BETWEEN :start_date AND :end_date GROUP BY date ORDER BY date", "variables": { "isrc": "USAT21301804", "start_date": "2026-04-08", "end_date": "2026-04-13" } }, { "question": "Full TikTok engagement summary for a track", "query": "SELECT SUM(views) AS total_views, SUM(creations) AS total_creations, SUM(likes) AS total_likes, SUM(favorites) AS total_favorites, SUM(shares) AS total_shares, SUM(comments) AS total_comments, SUM(streams) AS total_tiktok_streams FROM V_TIKTOK_BY_ISRC_COUNTRY_DAILY WHERE isrc = :isrc AND date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } } ] }, { "terms": [ "trending", "trending score", "trend score", "trending tracks", "staying power", "market lift", "days trending", "tadas", "tadas flag", "tadas score", "spotify lift", "apple lift", "tiktok lift", "what is trending", "whats hot" ], "targets": [ "FACTS.{{env}}.METRICS_TADAS", "FACTS.{{env}}.METRICS_TADAS_HYBRID" ], "related": ["FACTS.{{env}}.MAPPING_ISRC_TO_GLOBAL_PARTICIPANT"], "context": "Trending score tables (internally called TADAS - Trending Analytics Data and Scoring). In the Insights UI this is called 'Trending' - users may not know the TADAS name. METRICS_TADAS contains the core trend data; METRICS_TADAS_HYBRID combines multiple signal sources for per-ISRC lookups. MAPPING_ISRC_TO_GLOBAL_PARTICIPANT links ISRCs to artists for artist-level aggregation (join on isrc). Key columns: isrc, market (country code or 'GLOBAL'), tadas_days_trending, tadas_30days_score, tadas_trending_start_date, release_date, company_brand_uuids, parent_company_uuids, spotify_streams_1_day, apple_music_streams_1_day. Staying power is derived from tadas_30days_score: LOW (<=0.12), MEDIUM (<=0.24), HIGH (>0.24). TIERED TRENDING FLAGS (each has a boolean _flag and a numeric _lift percentage): TIER S (strongest signals): spotify_collection_flag/lift, spotify_lean_forward_flag/lift, tiktok_creations_global_flag/lift, tiktok_creations_country_flag/lift, spotify_search_flag/lift. TIER ONE: tiktok_views_global_flag/lift, tiktok_views_country_flag/lift, apple_lean_forward_flag/lift, apple_search_flag/lift, tiktok_likes_global_flag/lift, tiktok_likes_country_flag/lift. TIER TWO: apple_all_flag/lift. TIER THREE: spotify_all_flag/lift. The top 3 flags are selected by tier priority (S first), then within tier by lift value descending. Employee-only in the Insights UI.", "domain": "streaming", "priority": 3, "examples": [ { "question": "Currently trending tracks with high staying power", "query": "SELECT isrc, market, tadas_days_trending, tadas_30days_score, tadas_trending_start_date FROM METRICS_TADAS WHERE tadas_30days_score > 0.24 AND tadas_days_trending > 7 ORDER BY tadas_days_trending DESC LIMIT 20", "variables": {} }, { "question": "TADAS trends for a specific artist in a specific country", "query": "SELECT t.isrc, t.market, t.tadas_days_trending, t.tadas_30days_score, t.tadas_trending_start_date, t.spotify_collection_flag, t.spotify_lean_forward_flag, t.tiktok_creations_global_flag FROM METRICS_TADAS t JOIN MAPPING_ISRC_TO_GLOBAL_PARTICIPANT m ON m.isrc = t.isrc WHERE m.global_participant_id = :gp_id AND t.market = :market ORDER BY t.tadas_days_trending DESC", "variables": { "gp_id": "12345", "market": "ES" } }, { "question": "Is a specific track trending globally in TADAS", "query": "SELECT isrc, market, tadas_days_trending, tadas_30days_score, tadas_trending_start_date, spotify_collection_flag, spotify_collection_lift, spotify_lean_forward_flag, spotify_lean_forward_lift, tiktok_creations_global_flag, tiktok_creations_global_lift, apple_lean_forward_flag, apple_lean_forward_lift FROM METRICS_TADAS_HYBRID WHERE isrc = :isrc AND market = 'GLOBAL'", "variables": { "isrc": "USAT21301804" } }, { "question": "What countries and songs are trending for an artist", "query": "SELECT t.isrc, t.market, t.tadas_days_trending, t.tadas_30days_score FROM METRICS_TADAS t JOIN MAPPING_ISRC_TO_GLOBAL_PARTICIPANT m ON m.isrc = t.isrc WHERE m.global_participant_id = :gp_id AND t.tadas_days_trending > 0 ORDER BY t.tadas_days_trending DESC", "variables": { "gp_id": "12345" } } ] }, { "terms": [ "playlist placement", "playlist position", "on playlist", "added to playlist", "removed from playlist", "playlist history", "playlist adds", "peak position", "days on playlist", "playlist type" ], "targets": [ "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_PUBLIC", "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_COUNTRY_PRIVATE" ], "related": [ "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_PRIVATE", "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_PARTICIPANT_ISRC_PLAYLIST_PUBLIC", "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_PARTICIPANT_ISRC_PLAYLIST_COUNTRY_PRIVATE", "FACTS.{{env}}.V_PLAYLISTS_PLACEMENT_EVENTS_BY_ISRC_PLAYLIST", "FACTS.{{env}}.PLAYLISTS_PRIORITY_PLACEMENTS_BY_ISRC_PLAYLIST_PUBLIC", "FACTS.{{env}}.V_PLAYLISTS_PLACEMENTS_BY_TRACK_PLAYLIST_DISTRIBUTOR_PUBLIC", "FACTS.{{env}}.DBT_V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_PUBLIC" ], "context": "Playlist placement tables from ows-playlist. Track where songs appear on streaming platform playlists. Public tables contain position metadata (current_position, previous_position, peak_position, position_change, days_on_playlist, last_added_on_date, removed_on, first_added_on_date). Private tables additionally contain stream counts (streams_last_1_day, streams_last_7_days, streams_last_28_days, streams_last_183_days, streams_last_365_days, streams_all_time) and completion rates (completion_rate_last_1_day through completion_rate_all_time). Key columns: isrc, store_playlist_id, store_id (286=Spotify, 1=Apple Music, 187=Amazon, 348=Deezer, 453=YouTube, 708=Pandora), playlist_name, playlist_type (CURATED, EDITORIAL, PERSONALIZED, ALGORITHMIC, STATION, RADIO), playlist_follower_count, curator_name, curator_country, storefront. Participant variants add global_participant_id for artist-level queries. Events table tracks historical position changes (event_type: ADD_HISTORY, ADD_CURRENT, CHANGE, REMOVAL). To find a specific playlist by name, search V_PLAYLISTS_BY_PLAYLIST with playlist_name ILIKE '%search_term%'. For editorial playlists that an artist entered after a date, filter last_added_on_date >= :date AND playlist_type = 'EDITORIAL'. For playlist positions in specific countries, use curator_country (Spotify) or storefront (Apple Music).", "domain": "playlist", "priority": 3, "examples": [ { "question": "Current playlist placements for an ISRC", "query": "SELECT store_playlist_id, playlist_name, store_id, current_position, peak_position, days_on_playlist, playlist_follower_count, playlist_type FROM V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_PUBLIC WHERE isrc = :isrc AND removed_on IS NULL ORDER BY playlist_follower_count DESC", "variables": { "isrc": "USAT21301804" } }, { "question": "Position of a track on a specific named playlist in specific countries", "query": "SELECT p.playlist_name, p.curator_country, p.current_position, p.peak_position, p.days_on_playlist FROM V_PLAYLISTS_PLACEMENTS_BY_ISRC_PLAYLIST_PUBLIC p WHERE p.isrc = :isrc AND p.playlist_name ILIKE :playlist_name AND p.curator_country IN (:countries) AND p.removed_on IS NULL", "variables": { "isrc": "USAT21301804", "playlist_name": "%Daily Pop%", "countries": "'UK','AU','FR'" } }, { "question": "Editorial playlists an artist's tracks entered since a date", "query": "SELECT p.isrc, p.playlist_name, p.store_id, p.current_position, p.last_added_on_date, p.playlist_follower_count FROM V_PLAYLISTS_PLACEMENTS_BY_PARTICIPANT_ISRC_PLAYLIST_PUBLIC p WHERE p.global_participant_id = :gp_id AND p.playlist_type = 'EDITORIAL' AND p.last_added_on_date >= :since_date ORDER BY p.last_added_on_date DESC", "variables": { "gp_id": "12345", "since_date": "2026-02-01" } }, { "question": "Tracks from an artist on a specific named playlist", "query": "SELECT p.isrc, t.track_name, p.current_position, p.days_on_playlist FROM V_PLAYLISTS_PLACEMENTS_BY_PARTICIPANT_ISRC_PLAYLIST_PUBLIC p JOIN DIM_TRACK t ON t.isrc = p.isrc WHERE p.global_participant_id = :gp_id AND p.playlist_name ILIKE :playlist_name AND p.removed_on IS NULL", "variables": { "gp_id": "12345", "playlist_name": "%ACADEMIA PANCADA%" } }, { "question": "US Spotify playlists with over 20 million followers that have an artist's tracks added in 2026", "query": "SELECT p.playlist_name, p.isrc, t.track_name, p.current_position, p.playlist_follower_count, p.last_added_on_date FROM V_PLAYLISTS_PLACEMENTS_BY_PARTICIPANT_ISRC_PLAYLIST_PUBLIC p JOIN DIM_TRACK t ON t.isrc = p.isrc WHERE p.global_participant_id = :gp_id AND p.store_id = 286 AND p.curator_country = 'US' AND p.playlist_follower_count >= 20000000 AND p.last_added_on_date >= '2026-01-01' AND p.removed_on IS NULL ORDER BY p.playlist_follower_count DESC", "variables": { "gp_id": "12345" } } ] }, { "terms": [ "playlist streams", "streams from playlist", "playlist impact", "playlist vs total streams", "streams by playlist", "playlist stream contribution" ], "targets": [ "FACTS.{{env}}.STREAMS_BY_PLAYLIST_ROLLUP", "FACTS.{{env}}.STREAMS_BY_PLAYLIST_COUNTRY_ROLLUP" ], "related": [ "FACTS.{{env}}.STREAMS_BY_PLAYLIST_FEED_ROLLUP", "FACTS.{{env}}.STREAMS_BY_PLAYLIST_COUNTRY_FEED_ROLLUP", "FACTS.{{env}}.V_STREAMS_BY_PLAYLIST_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_TRACK_PLAYLIST_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_PLAYLIST_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "context": "Playlist stream contribution tables from ows-playlist. Measure how many streams a track received from being on a specific playlist. Rollup tables have aggregated totals; daily tables have per-day timeseries. Country variants add geographic breakdown. Feed variants add store-level detail. Key columns: isrc, store_playlist_id, country_code, feed_id, date, streams. Use to compare playlist-driven streams vs total streams and evaluate playlist impact. The track-level daily table (V_STREAMS_BY_TRACK_PLAYLIST_COUNTRY_FEED_DISTRIBUTOR_DAILY) provides the most granular view.", "domain": "playlist", "priority": 2, "examples": [ { "question": "Total streams from each playlist for an ISRC", "query": "SELECT store_playlist_id, SUM(streams) AS total_streams FROM STREAMS_BY_PLAYLIST_ROLLUP WHERE isrc = :isrc GROUP BY store_playlist_id ORDER BY total_streams DESC LIMIT 20", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "playlist metadata", "playlist info", "playlist name", "playlist followers", "playlist artwork", "playlist genre", "playlist curator", "playlist track count", "priority playlist", "hourly playlist", "editorial playlist", "filtr playlist", "filtr", "personalized playlist", "algorithmic playlist", "curated playlist", "new music friday playlist", "hot hits playlist" ], "targets": [ "FACTS.{{env}}.V_PLAYLISTS_BY_PLAYLIST", "FACTS.{{env}}.V_PLAYLIST_METADATA" ], "related": [ "FACTS.{{env}}.PRIORITY_PLAYLISTS", "FACTS.{{env}}.HOURLY_PLAYLISTS", "FACTS.{{env}}.V_PLAYLISTS_FOLLOWERS_BY_PLAYLIST_DATE_SPOTIFY", "FACTS.{{env}}.V_PLAYLISTS_AVAILABLE_STOREFRONTS_APPLE" ], "context": "Playlist metadata tables. V_PLAYLISTS_BY_PLAYLIST and V_PLAYLIST_METADATA contain playlist information: playlist_name, playlist_artwork_url, playlist_genres, playlist_track_count, playlist_follower_count, playlist_type (ALGORITHMIC, CHART, CURATED, EDITORIAL, HOT_HITS, NEW_MUSIC_FRIDAY, PERSONALIZED, RADIO, USER_GENERATED), playlist_uri, curator_name, curator_id, curator_country, owner, storefront. PRIORITY_PLAYLISTS and HOURLY_PLAYLISTS are curated lists of notable playlists. V_PLAYLISTS_FOLLOWERS_BY_PLAYLIST_DATE_SPOTIFY tracks daily Spotify follower count changes. V_PLAYLISTS_AVAILABLE_STOREFRONTS_APPLE lists Apple Music regional variants. graphql-knowledge uses V_PLAYLIST_METADATA with Snowflake Cortex Search for playlist text search. Playlist types include: ALGORITHMIC (auto-generated by DSP algorithms), CURATED (human-curated), EDITORIAL (DSP editorial team), PERSONALIZED (tailored to individual listeners like Discover Weekly or Daily Mix), HOT_HITS (e.g., Today's Top Hits), NEW_MUSIC_FRIDAY (weekly editorial additions), CHART (chart-based), RADIO, USER_GENERATED. 'filtr' is Sony Music's curated playlist brand across Spotify and Apple Music - filter by curator_name ILIKE '%filtr%' to find filtr playlists.", "domain": "playlist", "priority": 2, "examples": [ { "question": "Get metadata for a Spotify playlist", "query": "SELECT playlist_name, playlist_follower_count, playlist_track_count, playlist_type, playlist_genres, curator_name FROM V_PLAYLISTS_BY_PLAYLIST WHERE store_playlist_id = :playlist_id AND store_id = 286", "variables": { "playlist_id": "37i9dQZF1DXcBWIGoYBM5M" } } ] }, { "terms": [ "playlist demographics", "playlist listener age", "playlist listener gender", "who listens to playlist" ], "targets": ["FACTS.{{env}}.V_DEMOGRAPHICS_BY_PLAYLIST_COUNTRY"], "related": ["FACTS.{{env}}.V_PLAYLISTS_BY_PLAYLIST"], "context": "Playlist-level demographics from ows-playlist. Contains age group and gender breakdowns for listeners of a specific playlist, broken down by country. Key columns: store_playlist_id, country_code, age_group, gender, percentage. Only available for platforms that provide demographic data (primarily Spotify and Apple Music).", "domain": "playlist", "priority": 1 }, { "terms": [ "data availability", "data freshness", "latest data date", "highwatermark", "store data lag", "data recency", "when was data last updated" ], "targets": [ "FACTS.{{env}}.DATA_AVAILABILITY_BY_STORE_DAILY", "FACTS.{{env}}.DATA_AVAILABILITY_BY_STORE_DISTRIBUTOR_DAILY" ], "related": ["FACTS.{{env}}.DIM_FEED"], "context": "Data availability tables from ows-analytics. Track the latest date for which streaming/download data is available per store and distributor. Key columns: feed_id (store), distributor_id, date, data_type (streams, downloads, videos). Use to check data freshness before running analytics queries - if a store's latest available date is 3 days ago, queries for the last 2 days will show zero streams (missing data, not actual zero). The SKIPS_SAVES variant tracks data availability for skip and save metrics by feed.", "domain": "streaming", "priority": 2, "examples": [ { "question": "Latest available streaming data date per store", "query": "SELECT f.feed_name AS store_name, MAX(da.date) AS latest_date FROM DATA_AVAILABILITY_BY_STORE_DAILY da JOIN DIM_FEED f ON f.feed_id = da.feed_id GROUP BY f.feed_name ORDER BY latest_date DESC", "variables": {} } ] }, { "terms": [ "feed", "store feed", "dsp feed", "feed id", "store mapping", "streaming platform" ], "targets": ["FACTS.{{env}}.DIM_FEED"], "related": ["FACTS.{{env}}.DIM_STORE"], "context": "Feed dimension table mapping feed_id to store/platform names. COMPLETE STORE ID REFERENCE: 1=Apple Music (streams, downloads, SOS, demographics, playlists, charts), 4=Napster (streams), 187=Amazon Music (streams, downloads, SOS, playlists), 213=Beatport (downloads), 286=Spotify (streams, SOS, demographics, playlists, charts, followers, monthly listeners), 348=Deezer (streams, charts), 358=Shazam (shazam counts, charts), 453=YouTube (video metrics, SOS), 496=Google Play (streams, downloads), 708=Pandora (streams), 1202=TikTok (uses dedicated TIKTOK_* tables - NOT in DIM_FEED), 1405=VKontakte (streams, playlists, SOS), 1406=Odnoklassniki (streams), 1503=LINE Music Japan (streams), 1505=SoundCloud (streams, playlists, SOS), 1600=AWA (streams), 1601=Kuwo (streams), 1602=Kugou (streams), 1603=QQ Music (streams). The feed is the data pipeline identifier for each streaming platform. Analytics tables use feed_id for filtering. Join DIM_FEED to any streaming/download/video table to get human-readable store names. Distributors: 'theorchard', 'awal', 'sme' (Sony Music Entertainment).", "domain": "streaming", "priority": 2 }, { "terms": [ "video mapping", "video to track", "video to channel", "video to product", "video to artist", "isrc to video", "product to isrc", "product family", "primary product", "global participant mapping" ], "targets": [ "FACTS.{{env}}.MAPPINGS_VIDEO_TO_TRACKS_V3", "FACTS.{{env}}.MAPPINGS_VIDEO_TO_CHANNELS", "FACTS.{{env}}.MAPPINGS_VIDEO_TO_PRODUCTS" ], "related": [ "FACTS.{{env}}.MAPPINGS_VIDEO_TO_PARTICIPANTS", "FACTS.{{env}}.MAPPINGS_VIDEO_TO_ASSETS", "FACTS.{{env}}.MAPPINGS_PRODUCT_FAMILY_TO_ISRCS", "FACTS.{{env}}.MAPPINGS_PRODUCT_TO_PRIMARY_GLOBAL_PARTICIPANT", "FACTS.{{env}}.MAPPINGS_ISRC_TO_MIN_RELEASE_DATE", "FACTS.{{env}}.PRIMARY_PRODUCTS", "FACTS.{{env}}.MULTI_PRIMARY_PRODUCTS", "FACTS.{{env}}.GLOBAL_PARTICIPANT_BY_PRODUCT_ID_BY_ISRC", "FACTS.{{env}}.GLOBAL_PARTICIPANT_REPRESENTS_LABEL_PARTICIPANT" ], "context": "Mapping/crosswalk tables from ows-analytics linking entities across domains. MAPPINGS_VIDEO_TO_TRACKS_V3 links YouTube video_ids to ISRCs. MAPPINGS_VIDEO_TO_CHANNELS links videos to channels. MAPPINGS_VIDEO_TO_PRODUCTS links videos to product_ids. MAPPINGS_PRODUCT_FAMILY_TO_ISRCS groups ISRCs by product family (album). PRIMARY_PRODUCTS identifies the canonical product for each ISRC. MAPPINGS_PRODUCT_TO_PRIMARY_GLOBAL_PARTICIPANT links products to their primary artist. GLOBAL_PARTICIPANT_BY_PRODUCT_ID_BY_ISRC resolves artist identity at the track and product level. These tables are essential for joining analytics data across entity types (e.g., aggregating video views for all videos containing a specific ISRC).", "domain": "catalog", "priority": 1 }, { "terms": [ "market size", "market rank", "country market", "territory size", "market share by country" ], "targets": ["FACTS.{{env}}.MARKET_SIZE_BY_STORE_COUNTRY"], "related": [ "FACTS.{{env}}.FACT_MARKET_SHARE", "FACTS.{{env}}.DIM_COUNTRY" ], "context": "Market sizing data from ows-analytics. Contains total market size (total streams) by store and country, used for calculating market share and territory rankings. Key columns: store_id, country_code, total_streams, rank. Join with FACT_MARKET_SHARE for competitive market share data and DIM_COUNTRY for country names.", "domain": "analytics", "priority": 1 }, { "terms": [ "traffic source", "view source", "discovery source", "how viewers found", "youtube traffic" ], "targets": ["FACTS.{{env}}.DIM_TRAFFICSOURCE"], "related": [ "FACTS.{{env}}.V_VIEWS_BY_VIDEO_SOURCE_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.VIEWS_BY_CHANNEL_SOURCE_FEED_DISTRIBUTOR_DAILY" ], "context": "Traffic source dimension from ows-analytics. Maps traffic_source_id to human-readable traffic source names for YouTube video and channel analytics. Common sources: Browse features, Search, Suggested videos, External, Playlists, Channel pages, etc. Join to video/channel source tables to break down views by how viewers discovered the content.", "domain": "video", "priority": 1 }, { "terms": [ "source of streams", "sos", "lean back", "lean forward", "active source", "passive source", "algorithmic source", "editorial source", "release radio", "discover weekly", "daily mix", "collection", "library", "search source", "playlist source", "radio source", "stream source breakdown", "where streams come from", "where are streams coming from", "proportion of streams", "percentage of streams", "active vs passive", "active streams", "passive streams", "artist page source", "album page source", "play queue", "suggested videos", "youtube search source", "browse features", "musickit", "now playing" ], "targets": [ "FACTS.{{env}}.V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "context": "Source of Streams (SOS) data tracks where listeners discover and play music. The daily streams tables contain both high-level aggregate columns and per-DSP granular source columns. HIGH-LEVEL COLUMNS (on all daily streams tables): streams_active (user-initiated total), streams_passive (algorithmic/editorial total), streams_collection (library/saved music total). SPOTIFY SOS COLUMNS: streams_sos_spotify_collection, streams_sos_spotify_playqueue, streams_sos_spotify_albumpage, streams_sos_spotify_artistpage, streams_sos_spotify_search, streams_sos_spotify_playlists, streams_sos_spotify_releaseradar, streams_sos_spotify_discoverweekly, streams_sos_spotify_radio, streams_sos_spotify_dailymix, streams_sos_spotify_chart, streams_sos_spotify_other. APPLE MUSIC SOS COLUMNS: streams_sos_apple_library, streams_sos_apple_external, streams_sos_apple_voice, streams_sos_apple_search, streams_sos_apple_musickit, streams_sos_apple_nowplaying, streams_sos_apple_discovery, streams_sos_apple_other. AMAZON MUSIC SOS COLUMNS: streams_sos_amazon_userplaylist, streams_sos_amazon_songs, streams_sos_amazon_album, streams_sos_amazon_artist, streams_sos_amazon_search, streams_sos_amazon_playlist, streams_sos_amazon_station. YOUTUBE SOS COLUMNS: streams_sos_youtube_browse_features, streams_sos_youtube_direct_or_unknown, streams_sos_youtube_external, streams_sos_youtube_other_youtube_features, streams_sos_youtube_playlist_pages, streams_sos_youtube_playlists, streams_sos_youtube_suggested_videos, streams_sos_youtube_youtube_advertising, streams_sos_youtube_youtube_channels, streams_sos_youtube_youtube_search, streams_sos_youtube_misc_sources. SOS is available on V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY and country variants. Filter by download_activity_date (the date column on daily tables). 'Lean forward' = active/intentional streams; 'lean back' = passive/algorithmic streams. To compute proportion: streams_sos_spotify_playlists / NULLIF(streams, 0) * 100. Active sources (Spotify): collection, playqueue, albumpage, artistpage, search. Passive sources (Spotify): playlists, releaseradar, discoverweekly, radio, dailymix, chart.", "domain": "streaming", "priority": 3, "examples": [ { "question": "Spotify source of streams breakdown for a track over a date range", "query": "SELECT SUM(streams_sos_spotify_collection) AS collection, SUM(streams_sos_spotify_playqueue) AS play_queue, SUM(streams_sos_spotify_albumpage) AS album_page, SUM(streams_sos_spotify_artistpage) AS artist_page, SUM(streams_sos_spotify_search) AS search, SUM(streams_sos_spotify_playlists) AS playlists, SUM(streams_sos_spotify_releaseradar) AS release_radar, SUM(streams_sos_spotify_discoverweekly) AS discover_weekly, SUM(streams_sos_spotify_radio) AS radio, SUM(streams_sos_spotify_dailymix) AS daily_mix, SUM(streams_sos_spotify_chart) AS chart, SUM(streams_sos_spotify_other) AS other FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Active vs passive stream totals for a track on Spotify", "query": "SELECT SUM(streams_active) AS active_streams, SUM(streams_passive) AS passive_streams, SUM(streams_collection) AS collection_streams, SUM(streams) AS total_streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "YouTube Suggested Videos vs Search daily streams for a track", "query": "SELECT download_activity_date AS date, SUM(streams_sos_youtube_suggested_videos) AS suggested_videos, SUM(streams_sos_youtube_youtube_search) AS youtube_search FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 453 AND download_activity_date BETWEEN :start_date AND :end_date GROUP BY download_activity_date ORDER BY download_activity_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Apple Music source of streams breakdown for a track", "query": "SELECT SUM(streams_sos_apple_library) AS library, SUM(streams_sos_apple_external) AS external, SUM(streams_sos_apple_voice) AS voice, SUM(streams_sos_apple_search) AS search, SUM(streams_sos_apple_musickit) AS musickit, SUM(streams_sos_apple_nowplaying) AS now_playing, SUM(streams_sos_apple_discovery) AS discovery, SUM(streams_sos_apple_other) AS other FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 1 AND download_activity_date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } }, { "question": "Proportion of streams from each Spotify source for a track", "query": "SELECT ROUND(SUM(streams_sos_spotify_artistpage) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_artist_page, ROUND(SUM(streams_sos_spotify_playlists) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_playlists, ROUND(SUM(streams_sos_spotify_search) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_search, ROUND(SUM(streams_sos_spotify_collection) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_collection, ROUND(SUM(streams_sos_spotify_releaseradar) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_release_radar, ROUND(SUM(streams_sos_spotify_discoverweekly) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_discover_weekly, ROUND(SUM(streams_sos_spotify_radio) / NULLIF(SUM(streams), 0) * 100, 2) AS pct_radio FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } } ] }, { "terms": [ "skip rate", "skips", "completion rate", "saves", "saves to collection", "add to library", "save rate", "engagement metrics", "listener engagement", "listener retention", "how many saves", "skip percentage", "saves to collection for spotify", "saves to collection for apple" ], "targets": [ "FACTS.{{env}}.V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP", "FACTS.{{env}}.DATA_AVAILABILITY_SKIPS_SAVES_BY_FEED_SUMMARY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY" ], "context": "Skip rate and saves metrics from streaming analytics. Skip rate measures the percentage of streams where listeners skipped before the track finished - high skip rates may indicate poor listener fit or playlist misplacement. Saves (add to collection/library) measure intentional listener engagement - a save indicates the listener wants to hear the track again. Key columns: isrc, feed_id, date, skips, skip_rate, saves. Available per track, per store, and per country. DATA_AVAILABILITY_SKIPS_SAVES_BY_FEED_SUMMARY tracks which stores report skip/save data. Not all DSPs provide skip and save metrics - Spotify and Apple Music are the primary sources.", "domain": "streaming", "priority": 3, "examples": [ { "question": "Skip rate and saves for a track on Spotify over the last 7 days", "query": "SELECT download_activity_date AS date, skip_rate, saves, streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date >= DATEADD('day', -7, CURRENT_DATE()) ORDER BY download_activity_date", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "brand", "company brand", "parent company", "orchard brand", "awal brand", "sme brand", "sony brand", "service tier", "brand filter", "brand breakdown" ], "targets": [ "FACTS.{{env}}.VENDOR_COMPANY_BRAND_PARENT_COMPANY_SERVICE_TIER_VIEW" ], "related": ["FACTS.{{env}}.DIM_VENDOR", "FACTS.{{env}}.DIM_BRAND"], "context": "Company brand hierarchy view from ows-analytics. Links vendors to their company brand (The Orchard, AWAL, Sony Music Entertainment), parent company, and service tier. Key columns: vendor_id, company_brand_name, parent_company_name, service_tier. Use to aggregate streaming/revenue data by brand or filter to specific brands. Common brands: 'The Orchard', 'AWAL', 'SME' (Sony Music Entertainment). Join to streaming/analytics tables via vendor_id or label_id for brand-level aggregation.", "domain": "analytics", "priority": 2, "examples": [ { "question": "Total streams by company brand", "query": "SELECT cb.company_brand_name, SUM(m.streams_28_days) AS total_streams FROM METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP m JOIN VENDOR_COMPANY_BRAND_PARENT_COMPANY_SERVICE_TIER_VIEW cb ON cb.vendor_id = m.label_id GROUP BY cb.company_brand_name ORDER BY total_streams DESC", "variables": {} }, { "question": "Total streams by brand for specific artists in a date range", "query": "SELECT cb.company_brand_name, SUM(s.streams) AS total_streams FROM V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY s JOIN VENDOR_COMPANY_BRAND_PARENT_COMPANY_SERVICE_TIER_VIEW cb ON cb.vendor_id = s.label_id WHERE s.global_participant_id IN (:gp_ids) AND s.download_activity_date BETWEEN :start_date AND :end_date GROUP BY cb.company_brand_name ORDER BY total_streams DESC", "variables": { "gp_ids": "123, 456, 789", "start_date": "2026-01-01", "end_date": "2026-01-31" } } ] }, { "terms": [ "release date", "release week", "first week streams", "first week performance", "launch week", "opening week", "release day", "new release", "album release", "single release", "min release date", "latest release", "latest album", "most recent album", "newest album", "last album", "most recent release", "first n days", "first 5 days", "first 3 days" ], "targets": ["FACTS.{{env}}.MAPPINGS_ISRC_TO_MIN_RELEASE_DATE"], "related": [ "FACTS.{{env}}.DIM_RELEASE", "FACTS.{{env}}.V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.METRICS_BY_TRACK_FEED_DISTRIBUTOR_ROLLUP" ], "context": "Release date mapping table linking ISRCs to their earliest release date. Key columns: isrc, min_release_date. Use for first-week performance analysis by joining to daily streaming tables and filtering to 7 days from release date. Pattern: JOIN MAPPINGS_ISRC_TO_MIN_RELEASE_DATE m ON m.isrc = s.isrc WHERE s.download_activity_date BETWEEN m.min_release_date AND DATEADD('day', 6, m.min_release_date). Useful for comparing first-week performance across releases or albums, benchmarking new releases against catalog, and identifying release-driven spikes in streaming data.", "domain": "catalog", "priority": 3, "examples": [ { "question": "First week streams for a track", "query": "SELECT s.download_activity_date AS date, SUM(s.streams) AS streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY s JOIN MAPPINGS_ISRC_TO_MIN_RELEASE_DATE m ON m.isrc = s.isrc WHERE s.isrc = :isrc AND s.download_activity_date BETWEEN m.min_release_date AND DATEADD('day', 6, m.min_release_date) GROUP BY s.download_activity_date ORDER BY s.download_activity_date", "variables": { "isrc": "USAT21301804" } }, { "question": "First N days streams for an album (all tracks summed)", "query": "SELECT s.download_activity_date AS date, SUM(s.streams) AS daily_streams FROM V_STREAMS_BY_PRODUCT_TRACK_FEED_DISTRIBUTOR_DAILY s JOIN MAPPINGS_ISRC_TO_MIN_RELEASE_DATE m ON m.isrc = s.isrc WHERE s.product_id = :product_id AND s.download_activity_date BETWEEN m.min_release_date AND DATEADD('day', :days - 1, m.min_release_date) GROUP BY s.download_activity_date ORDER BY s.download_activity_date", "variables": { "product_id": "67890", "days": "5" } } ] }, { "terms": [ "global sound recording", "recording metadata", "song metadata", "isrc metadata", "track metadata", "release date lookup", "artist lookup by isrc" ], "targets": ["FACTS.{{env}}.GLOBAL_SOUND_RECORDING"], "related": [ "FACTS.{{env}}.DIM_TRACK", "FACTS.{{env}}.MAPPINGS_ISRC_TO_MIN_RELEASE_DATE", "FACTS.{{env}}.GLOBAL_PARTICIPANT_BY_PRODUCT_ID_BY_ISRC" ], "context": "Global sound recording metadata table. Contains cross-platform recording information: isrc, recording_name, artist_name, release_date, global_participant_id. Aggregated from multiple sources. Note: release_date may not be populated for all tracks, particularly non-SME/non-Orchard tracks. For reliable release dates, prefer MAPPINGS_ISRC_TO_MIN_RELEASE_DATE. Use for resolving ISRC to human-readable track/artist names and linking to artist-level analytics.", "domain": "catalog", "priority": 1 }, { "terms": [ "latin iberia", "cis", "ex us", "outside us", "regional breakdown", "territory grouping", "region streams", "streams by region", "top in region", "regional streaming" ], "targets": [ "FACTS.{{env}}.STREAMS_BY_TRACK_COUNTRY_REGION_FEED_DISTRIBUTOR_ROLLUP" ], "related": [ "FACTS.{{env}}.DIM_COUNTRY", "FACTS.{{env}}.V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP" ], "context": "Pre-aggregated region-level streaming rollup and region-to-country mapping for territory analysis. REGION DEFINITIONS: NORDICS = SE, NO, DK, FI, IS. LATIN_IBERIA = AR, BO, BR, CL, CO, CR, CU, DO, EC, SV, GT, HN, MX, NI, PA, PY, PE, PR, ES, UY, VE, PT. DACH = DE, AT, CH. CIS = RU, UA, BY, KZ, UZ, GE, AM, AZ, MD, KG, TJ, TM. EUROPE = GB, FR, IT, NL, BE, PL, IE, SE, NO, DK, FI, PT, ES, DE, AT, CH, CZ, HU, RO, BG, HR, SK, SI, EE, LV, LT, GR, CY, MT, LU. NORTH_AMERICA = US, CA. OCEANIA = AU, NZ. EX_US = everything except US. For region-level queries, either use STREAMS_BY_TRACK_COUNTRY_REGION_FEED_DISTRIBUTOR_ROLLUP (pre-aggregated) or filter country_code IN (...) on country-level daily/rollup tables. When users say 'Nordics', 'LatAm', 'Latin-Iberia', 'DACH', etc., map to the country code list and query accordingly. Note: regions overlap - EUROPE includes countries from NORDICS, DACH, and parts of LATIN_IBERIA. Do not sum regions to compute global totals.", "domain": "streaming", "priority": 2, "examples": [ { "question": "Top tracks in the Nordics region by 7-day streams", "query": "SELECT m.isrc, t.track_name, SUM(m.streams_7_days) AS nordic_streams FROM DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP m JOIN DIM_TRACK t ON t.isrc = m.isrc WHERE m.country_code IN ('SE', 'NO', 'DK', 'FI', 'IS') GROUP BY m.isrc, t.track_name ORDER BY nordic_streams DESC LIMIT 10", "variables": {} }, { "question": "Top tracks in Latin-Iberia by streams in a date range", "query": "SELECT s.isrc, t.track_name, SUM(s.streams) AS total_streams FROM DBT_V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY s JOIN DIM_TRACK t ON t.isrc = s.isrc WHERE s.country_code IN ('AR', 'BO', 'BR', 'CL', 'CO', 'CR', 'CU', 'DO', 'EC', 'SV', 'GT', 'HN', 'MX', 'NI', 'PA', 'PY', 'PE', 'PR', 'ES', 'UY', 'VE', 'PT') AND s.download_activity_date BETWEEN :start_date AND :end_date GROUP BY s.isrc, t.track_name ORDER BY total_streams DESC LIMIT 10", "variables": { "start_date": "2026-01-27", "end_date": "2026-02-01" } } ] }, { "terms": [ "product type", "release format", "single format", "ep format", "full length", "compilation", "album vs single", "is it an album or single", "release type", "product format", "singles vs albums" ], "targets": ["FACTS.{{env}}.DIM_RELEASE"], "related": [ "FACTS.{{env}}.DIM_TRACK", "FACTS.{{env}}.DIM_TRACK_CLEAN_MV" ], "context": "Product/release type information from the DIM_RELEASE dimension table. Key columns: product_id, release_name, release_date, format (values: 'Full Length' for albums, 'Single' for singles, 'EP' for extended plays), product_type, labelid, subaccountid, artistid, display_upc, not_for_distribution, compilation (boolean). DIM_TRACK_CLEAN_MV has offer_type (values: 'all', 'album_download_stream', 'stream_only', 'track_download_stream'). Use format to distinguish albums from singles. To list releases by type with streams, join DIM_RELEASE to streaming rollup tables via product_id. not_for_distribution accepted values for analytics: 'N', 'SMEAnalyticsDummy', 'EditoriallySuspectContent', 'SwitchboardDummy'.", "domain": "catalog", "priority": 2, "examples": [ { "question": "List all singles vs albums for an artist with their total streams", "query": "SELECT r.product_id, r.release_name, r.format, r.release_date, SUM(m.streams_all_time) AS total_streams FROM DIM_RELEASE r JOIN METRICS_BY_PRODUCT_FEED_DISTRIBUTOR_ROLLUP m ON m.product_id = r.product_id WHERE r.artistid = :artist_id AND r.not_for_distribution = 'N' GROUP BY r.product_id, r.release_name, r.format, r.release_date ORDER BY total_streams DESC", "variables": { "artist_id": "12345" } }, { "question": "Count albums vs singles in top streaming results for a country", "query": "WITH top_tracks AS (SELECT m.isrc, m.streams_7_days FROM DBT_V_METRICS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_ROLLUP m WHERE m.country_code = :country ORDER BY m.streams_7_days DESC LIMIT 10) SELECT r.format, COUNT(DISTINCT r.product_id) AS product_count FROM top_tracks tt JOIN DIM_TRACK_CLEAN_MV t ON t.isrc = tt.isrc JOIN DIM_RELEASE r ON r.product_id = t.product_id AND r.not_for_distribution = 'N' GROUP BY r.format", "variables": { "country": "FI" } } ] }, { "terms": [ "subscription tier", "subscription breakdown", "paid streams", "free tier streams", "ad supported streams", "mid tier streams", "subscription type", "premium streams", "free streams", "stream quality" ], "targets": [ "FACTS.{{env}}.V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_ACCOUNT_TRACK_FEED_DISTRIBUTOR_DAILY" ], "related": [ "FACTS.{{env}}.V_STREAMS_BY_TRACK_COUNTRY_FEED_DISTRIBUTOR_DAILY", "FACTS.{{env}}.V_STREAMS_BY_PARTICIPANT_TRACK_FEED_DISTRIBUTOR_DAILY" ], "context": "Subscription tier breakdown columns on daily streaming tables. Columns: sub_type_subscription (streams from paid/premium subscribers - generate higher royalty rates), sub_type_adsupported (streams from free/ad-supported tier listeners), sub_type_midtier (streams from mid-tier subscription plans). These columns are on V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY and all entity-level variants. Use to understand stream value - paid streams generate significantly more revenue per stream than ad-supported. Not all DSPs report subscription tier. Spotify is the primary DSP where subscription tier breakdown is meaningful (free, mid-tier, premium). Apple Music streams are effectively all premium (no free tier).", "domain": "streaming", "priority": 1, "examples": [ { "question": "Subscription tier breakdown for a track on Spotify", "query": "SELECT SUM(sub_type_subscription) AS paid_streams, SUM(sub_type_adsupported) AS free_streams, SUM(sub_type_midtier) AS midtier_streams, SUM(streams) AS total_streams FROM DBT_V_STREAMS_BY_TRACK_FEED_DISTRIBUTOR_DAILY WHERE isrc = :isrc AND feed_id = 286 AND download_activity_date BETWEEN :start_date AND :end_date", "variables": { "isrc": "USAT21301804", "start_date": "2026-01-01", "end_date": "2026-01-31" } } ] }, { "terms": [ "entity resolution", "identity resolution", "find artist by name", "find song by name", "resolve isrc", "resolve artist", "look up artist", "look up track", "artist to isrc", "isrc to product", "product to label", "who is this artist", "what is this song", "spotify id", "spotify artist id", "apple music id", "apple id", "find by spotify id", "look up by id" ], "targets": [ "FACTS.{{env}}.GLOBAL_SOUND_RECORDING", "FACTS.{{env}}.GLOBAL_PARTICIPANT_BY_PRODUCT_ID_BY_ISRC" ], "related": [ "FACTS.{{env}}.DIM_TRACK", "FACTS.{{env}}.DIM_RELEASE", "FACTS.{{env}}.DIM_ARTIST", "FACTS.{{env}}.MAPPINGS_ISRC_TO_MIN_RELEASE_DATE", "FACTS.{{env}}.MAPPINGS_PRODUCT_TO_PRIMARY_GLOBAL_PARTICIPANT" ], "context": "Entity resolution workflow for connecting names to analytics data. STEP 1 - Resolve artist or song name: Use GraphQL globalParticipantSearchES(term) for artists or globalSoundRecordingSearchES(term) for songs. This returns global_participant_id or isrc. STEP 2 - Resolve Spotify/Apple IDs: Use GraphQL globalParticipantBySpotifyId(spotifyId) or globalParticipantByAppleMusicId(appleId) to get global_participant_id from platform IDs. STEP 3 - Snowflake joins: GLOBAL_SOUND_RECORDING maps isrc -> recording_name, artist_name, global_participant_id. GLOBAL_PARTICIPANT_BY_PRODUCT_ID_BY_ISRC maps isrc + product_id -> global_participant_id. DIM_TRACK maps isrc -> track details. DIM_RELEASE maps product_id -> release details including labelid, format, release_date. MAPPINGS_PRODUCT_TO_PRIMARY_GLOBAL_PARTICIPANT maps product_id -> primary artist. DIM_ARTIST maps artist_id -> artist name. Always resolve names via GraphQL search first, then use the returned IDs for Snowflake analytics queries.", "domain": "catalog", "priority": 2, "examples": [ { "question": "Get track and artist metadata for an ISRC from Snowflake", "query": "SELECT g.isrc, g.recording_name, g.artist_name, g.global_participant_id, m.min_release_date FROM GLOBAL_SOUND_RECORDING g LEFT JOIN MAPPINGS_ISRC_TO_MIN_RELEASE_DATE m ON m.isrc = g.isrc WHERE g.isrc = :isrc", "variables": { "isrc": "USAT21301804" } } ] }, { "terms": [ "customer master", "store name mapping", "customer master master" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.CUSTOMER_MASTER_MASTER" ], "context": "Master mapping table linking store IDs to store names (Spotify, Apple Music, YouTube, etc.). Used in REVENUE_BY_STORE_DBT via COLLATE('en-ci') for case-insensitive store name matching. Key columns: customer_id, customer_name.", "domain": "vendor", "source": "schema-analysis", "priority": 1, "related": ["FACTS.{{env}}.DIM_STORE"] }, { "terms": [ "oar vendor", "vendor account info", "vendor master", "vendor master data" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.VENDOR" ], "context": "Vendor/account master record from the Orchard application. Contains vendor_id, vendor_name, and account metadata. Used in ACCOUNT_STATEMENT_PERIODS_DBT and WORKSTATION_SUMMARY_DBT to map accounts to vendors.", "domain": "vendor", "source": "schema-analysis", "priority": 1, "related": [ "FACTS.{{env}}.DIM_VENDOR", "ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_ACCOUNT" ] }, { "terms": [ "oar releases", "release metadata oar", "upc releases", "release catalog data" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.RELEASES" ], "related": ["FACTS.{{env}}.DIM_RELEASE"], "context": "Release/product metadata from the Orchard application. Contains release_id, UPC, product_type, label_id. Used in REVENUE_DISTRO_DBT and expense models. Deduplicated using ROW_NUMBER() OVER (PARTITION BY upc, product_type, labelid) with rn = 1.", "domain": "catalog", "source": "schema-analysis", "priority": 1 }, { "terms": ["oar track", "track metadata oar"], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.TRACK" ], "related": ["FACTS.{{env}}.DIM_TRACK"], "context": "Track/recording metadata from the Orchard application. Contains track_unique_id for joining to dim_track. Used in REVENUE_BY_RECORDING_DISTRO_DBT for track-level revenue attribution.", "domain": "catalog", "source": "schema-analysis", "priority": 1 }, { "terms": ["oar subaccount", "vendor subaccount"], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.SUBACCOUNT" ], "context": "Vendor account subdivisions from the Orchard application. Subaccounts partition vendor accounts for more granular royalty tracking. Used in REVENUE_BY_SUBACCOUNT_DBT.", "domain": "vendor", "source": "schema-analysis", "priority": 1, "related": ["ROYALTY_ACCOUNTING.{{env}}.REVENUE_BY_SUBACCOUNT_DBT"] }, { "terms": ["oar artist info", "artist metadata oar", "artist metadata"], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.ARTIST_INFO" ], "related": ["FACTS.{{env}}.DIM_ARTIST"], "context": "Artist metadata from the Orchard application. Used in COMBINED_EXPENSES_DBT for artist-level expense attribution.", "domain": "catalog", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar contract", "raw contract", "abacus contract source", "distribution deal", "neighbouring rights contract" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.CONTRACT_DBT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_LIFECYCLE", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_TERM", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_CONTRACT" ], "context": "Raw contract records from the Abacus royalty accounting system. The core entity representing a royalty deal. contract_type: distribution, legacy_distribution, neighbouring_rights. Key flags: is_primary_contract, is_paythrough_contract (earnings flow through to sub-labels), is_excluded_from_accounting_run (temporarily exempt from calculation). Linked to accounts via ACCOUNT_CONTRACT, rates via CONTRACT_TERM -> CONTRACT_TERM_CONDITION, lifecycle via CONTRACT_LIFECYCLE. Key columns: contract_id, contract_name, contract_type, reference_signing_entity_id, term_start, term_end, initial_start_date, execution_date.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": ["account contract mapping", "account contract link"], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_CONTRACT" ], "context": "Maps accounts to contracts in Abacus. Used extensively in ledger, statement, and revenue models to scope data by account. Key columns: account_id, contract_id, ledger_account_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1, "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_CONTRACT"] }, { "terms": ["adjustment type reference", "adjustment type lookup"], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_ADJUSTMENT_TYPE" ], "context": "Reference/lookup table for adjustment types in Abacus. Provides reference_adjustment_type_name for adjustment type IDs. Type ID 65 separates expenses from adjustments in dbt models. Used in COMBINED_ADJUSTMENTS_DBT and COMBINED_EXPENSES_DBT.", "domain": "accounting", "source": "schema-analysis", "priority": 1, "related": ["ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADJUSTMENTS_DBT"] }, { "terms": ["oar exchange rate", "currency exchange oar"], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.EXCHANGE_RATE" ], "related": ["FACTS.{{env}}.CURRENCY_EXCHANGE_RATES"], "context": "Currency exchange rates from the Abacus system. Used in Workstation models for converting between sale currency, USD, and payee currency. Distinct from FACTS.CURRENCY_EXCHANGE_RATES which are period-specific rates used during accounting runs.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar account", "raw account", "abacus account source", "account master data" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.VW_DIM_ABACUS_ACCOUNT"], "context": "Core entity representing a royalty payee (artist, label, or rights holder). Every contract, payment, and tax record ties back to an account. Source table for VW_DIM_ABACUS_ACCOUNT. Key columns: account_id (PK), account_name, created_by.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "payment terms", "payment schedule", "payment minimum", "payout frequency" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_PAYMENT_TERM" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "context": "Payment configuration per account - currency, minimum threshold, payment schedule (30/45/60/90 days after month/quarter/half-year end), and payment entity assignment. Key columns: account_id, currency_code, payment_minimum, payment_schedule, payment_entity_id, agreement_type_id.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "tax info", "withholding tax config", "vat exemption", "tax residence" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_TAX_INFO" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "context": "Tax compliance configuration per account - country of residence, VAT exemption, withholding tax applicability, treaty claims, and WHT rate overrides. Key columns: account_id, country_of_tax_residence, is_vat_exempt, is_tax_treaty_claimed, is_wht_applicable, wht_rate_override.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "account payee", "payoneer payee", "payment method", "disbursement config" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_PAYEE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "context": "Links accounts to Payoneer payment profiles and SAP vendor IDs. Determines how royalties are disbursed. Key columns: account_id, payoneer_payee_id, payoneer_program_id, sap_vendor_id, reference_payment_type_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "payment hold", "payment freeze", "hold reason", "payment blocked" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.PAYMENT_HOLD" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "context": "Flags accounts where payments are blocked for compliance, legal, or operational reasons. Each account has at most one hold record. Key columns: account_id (unique), is_on_hold, reason, start_date.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "contract lifecycle", "contract status", "active contract", "terminated contract", "contract renewal" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_LIFECYCLE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT" ], "context": "Tracks the lifecycle state of contracts: init -> active -> to_be_terminated -> terminated -> in_collection_period -> inactive. Contains key dates for renewals, terminations, and collection windows. Key columns: contract_id, lifecycle_status, lifecycle_term_start, lifecycle_term_end, renewal_effective, termination_effective, collection_start, collection_end.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "contract term", "royalty rate term", "rate structure", "base term", "override term" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_TERM" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_TERM_CONDITION" ], "context": "Defines royalty rate structures within a contract. Each contract has a base term and optional override terms scoped by type (artist, catalog, label, product, track, contributor/contribution schedule). Key columns: contract_term_id, contract_id, term_type, contract_term_name, is_base_term, attachments (JSON with ISRCs/UPCs).", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "term condition", "royalty rate condition", "rate tier", "commission rate" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_TERM_CONDITION" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_TERM" ], "context": "Specific rate conditions within a contract term, defining the actual royalty rate, commission, and matching conditions (country/store/transaction type filters) with priority ordering. Key columns: contract_term_id, conditions (JSON), term_rate, commission, priority.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "raw contract advance", "advance payment source", "advance status", "advance milestone" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_ADVANCE" ], "related": ["ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADVANCES_DBT"], "context": "Raw advance payment records from Abacus. Source for COMBINED_ADVANCES_DBT. Tracks advance amounts, milestones, and status lifecycle: not_qualified -> qualified -> in_review -> approved -> pending_payment -> paid. Key columns: contract_id, amount, currency_code, milestone, milestone_date, advance_status, vat_amount, withholding_tax_amount.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "raw contract reserve", "reserve config", "holdback rate", "reserve release schedule" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_RESERVE" ], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_BALANCES_LOOKER_V2" ], "context": "Reserve holdback configuration per contract - the percentage of royalties withheld and the installment-based release schedule. Key columns: contract_id, reserve_rate, reserve_release_offset_in_months, installments_in_months, release_schedule (JSON).", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "raw contract flowthrough", "flowthrough config", "paythrough rate", "recoupment cap" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_FLOWTHROUGH" ], "related": [ "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_AUTOMATED_FLOWTHROUGH" ], "context": "Flowthrough (pass-through) payment configuration per contract. Controls the percentage of revenue passed through to sub-distributors with shutoff and pause controls. Key columns: contract_id, flowthrough_rate, flowthrough_status (active/shutoff/paused), has_automatic_shutoff, recoupment_cap.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "contract party", "artist contract link", "contributor contract", "label contract link" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_PARTY" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT" ], "context": "Associates contributors (artists) or labels with a contract. The target_type field is either 'contributor' or 'label', and target_id is the external artist/label identifier. Used to determine which catalog items are in scope for a contract.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "mechanical deduction", "mechanical royalty", "admin fee", "usa mechanical" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_MECHANICAL_DEDUCTION" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT" ], "context": "Mechanical royalty deduction configuration per contract for specific territories (USA/CAN/ROW). Covers deduction type (digital/physical) and admin fees. Key columns: contract_id, territory, mechanical_type, admin_type, admin_fee.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar signing entity", "legal entity", "company code", "signing entity reference" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_SIGNING_ENTITY" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_PAYMENT_ENTITY" ], "context": "Legal entity that signs contracts. Links to SAP profit center and payment entity. Key columns: reference_signing_entity_id, legal_name, company_code, vat_number, reference_payment_entity_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": ["payment entity", "paying company", "payment organization"], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_PAYMENT_ENTITY" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_SIGNING_ENTITY" ], "context": "Organization responsible for making payments (e.g., The Orchard US, The Orchard UK). Defines country of tax reporting. Key columns: reference_payment_entity_id, payment_entity_name, country_of_tax_reporting.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "legacy contract", "vendor contract", "oa contract", "deal terms", "digital split" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.VENDOR_CONTRACT" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT" ], "context": "Legacy contract terms from Orchard Admin (workstation). Contains detailed deal terms including digital/physical splits, advance amounts, reserve rates, and territory carve-outs. Synced to Abacus via ows-abacus-legacy-sync. Key columns: vendor_id, cont_start, cont_end, contract_type, digital_split, physical_split, reserve_rate, advance_payment, payment_interval, currency_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": ["country reference", "territory lookup", "iso country code"], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.COUNTRY" ], "context": "Reference table for all countries and territories. Used for territory carve-outs on contracts, royalty collection territory resolution, and joins in reporting views. Key columns: id, name, country_code (ISO 2-letter), iso3166a3 (ISO 3-letter), continent.", "domain": "vendor", "source": "schema-analysis", "priority": 1, "related": ["FACTS.{{env}}.DIM_COUNTRY"] }, { "terms": [ "currency reference", "iso 4217", "payout currency", "currency code lookup" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.CURRENCIES" ], "context": "Currency reference table mapping IDs to ISO 4217 codes. Used to resolve currency_id in contract and payment terms. Key columns: id, ISO_4217_code, currency_name, symbol_html_entity_code, supported_payout_currency.", "domain": "vendor", "source": "schema-analysis", "priority": 1, "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.EXCHANGE_RATE" ] }, { "terms": [ "track artist", "artist credit", "featured artist", "track artist link" ], "targets": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.TRACK_ARTIST" ], "related": [ "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.ARTIST_INFO", "ORCHARD_APP_REPORTING_V2.ART_RELATIONS_PROD_ART_RELATIONS.TRACK" ], "context": "Join table linking tracks to artists. Resolves which artists appear on which tracks and in what role. Key columns: track_id, artist_info_id, role.", "domain": "catalog", "source": "schema-analysis", "priority": 1 }, { "terms": [ "raw worksheet adjustment", "manual adjustment source", "adjustment entry", "royalty correction entry" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.VW_ABACUS_ADJUSTMENTS_V2", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT_DETAIL", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_APPLIED", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.STATEMENT_PERIOD_ADJUSTMENT_FILE" ], "context": "Raw manual monetary corrections to an account's royalty balance for a specific period. Source table for VW_ABACUS_ADJUSTMENTS_V2. Adjustments are uploaded via CSV/Excel or auto-generated (flowthrough). Lifecycle: created -> approved (via abacus_state) -> applied (creates ledger_adjustment_applied). Key columns: worksheet_adjustment_id, account_id, contract_id, activity_statement_period_id, apply_to_statement_period_id, reference_adjustment_type_id, adjustment_amount, adjustment_currency_code, apply_to_flowthrough_payment, note, internal_note. Soft-deletable via deleted_at/deleted_by.", "domain": "accounting", "source": "schema-analysis", "priority": 2 }, { "terms": [ "adjustment detail", "adjustment line item", "upc adjustment", "product level adjustment" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT_DETAIL" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_DETAIL_APPLIED" ], "context": "Line-item detail of a worksheet adjustment, breaking it down by UPC (product) and distribution type (digital/physical). When a detail row exists, its amount, note, and adjustment type override the parent worksheet_adjustment values. Key columns: worksheet_adjustment_detail_id, worksheet_adjustment_id, account_id, contract_id, upc, distribution_type (digital/physical), amount, currency_code, reference_adjustment_type_id, note, internal_note.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "adjustment file", "adjustment batch", "upload adjustments", "adjustment import", "approve adjustments" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.STATEMENT_PERIOD_ADJUSTMENT_FILE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT_DETAIL" ], "context": "Batch container for adjustment uploads. Users upload an Excel/CSV file or the system auto-generates one (flowthrough). batch_type: auto, manual, upload. Lifecycle tracked via abacus_state: upload_file -> validate_file -> import_file -> approve_file -> apply_file. Derived status values: not_approved, approved, applied, generating, failed_to_generate, no_records. Key columns: statement_period_adjustment_file_id, statement_period_id, file_name, batch_type, valid_row_count, invalid_row_count, total_file_amount_multicurrency, md5sum, error_type.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar applied adjustment", "oar ledger adjustment applied", "raw finalized adjustment", "adjustment applied to ledger" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_APPLIED" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_DETAIL_APPLIED", "ROYALTY_ACCOUNTING.{{env}}.LEDGER_ADJUSTMENT_DETAIL" ], "context": "Finalized adjustment entries posted to the accounting ledger. Created when a worksheet_adjustment is approved and applied. Includes currency conversion from adjustment currency to payee currency. A worksheet_adjustment with no matching ledger_adjustment_applied row is considered 'pending'. Key columns: ledger_adjustment_applied_id, abacus_event_id, account_id, contract_id, statement_period_id, adjustment_amount, adjustment_currency_code, adjustment_amount_payee_currency, worksheet_adjustment_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar applied adjustment detail", "oar ledger adjustment detail applied", "raw upc applied adjustment" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_DETAIL_APPLIED" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT_DETAIL", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_ADJUSTMENT_APPLIED" ], "context": "Finalized detail-level adjustment entries in the ledger, linking worksheet_adjustment_detail to the applied ledger record. Contains per-UPC/product amounts with payee currency conversion. Key columns: ledger_adjustment_detail_applied_id, worksheet_adjustment_id, worksheet_adjustment_detail_id, adjustment_amount, adjustment_currency_code, adjustment_amount_payee_currency.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "worksheet correction", "revenue correction", "royalty reversal", "gross net correction" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_CORRECTION" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_ADJUSTMENT", "ROYALTY_ACCOUNTING.{{env}}.LEDGER_CORRECTION" ], "context": "Manual corrections to previously booked royalty results - distinct from adjustments. correction_type: royalty_reversal, royalty_correction. Applied to the ledger via ledger_correction. Reverses or corrects gross_revenue, distribution_fee, and net_revenue amounts. Key columns: account_id, contract_id, statement_period_id, correction_type, gross_revenue, distribution_fee, net_revenue, currency_code.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "worksheet flowthrough", "flowthrough worksheet", "flowthrough batch", "auto flowthrough" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_FLOWTHROUGH" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.WORKSHEET_FLOWTHROUGH_BATCH", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_FLOWTHROUGH", "ROYALTY_ACCOUNTING_REPORTING.{{env}}.VW_ABACUS_AUTOMATED_FLOWTHROUGH" ], "context": "Flowthrough (pass-through) payment calculation entries generated during accounting runs. Tracks amounts flowing through from parent to sub-distributor contracts. Related batch table WORKSHEET_FLOWTHROUGH_BATCH tracks batch_status for grouped processing.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "advance recoupment", "advance applied", "advance recouped", "advance deduction" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.LEDGER_CONTRACT_ADVANCE_APPLIED" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_ADVANCE", "ROYALTY_ACCOUNTING.{{env}}.COMBINED_ADVANCES_DBT" ], "context": "Records when contract advance payments are recouped (deducted from earned royalties). Created during accounting runs when earned royalties offset outstanding advance balances. Key columns: contract_id, contract_advance_id, abacus_event_id, recouped_amount.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "oar transaction type", "transaction type reference", "streaming download physical type", "revenue transaction category" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_TRANSACTION_TYPE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_TRANSACTION_TYPE_GROUP" ], "context": "Taxonomy of revenue transaction types (streaming, download, physical, ringtone, etc.) and their groupings. Used in contract_term_condition to define rate conditions per transaction type. REFERENCE_TRANSACTION_TYPE_GROUP groups types into broader categories. Key columns: reference_transaction_type_id, type_name, reference_transaction_type_group_id.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "mechanical rate reference", "statutory mechanical rate", "mechanical royalty rate by country" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.REFERENCE_MECHANICAL_RATE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_MECHANICAL_DEDUCTION" ], "context": "Statutory mechanical royalty rates by country. Used to calculate mechanical deductions on contracts. Key columns: country_code, base_rate, minute_rate, ringtone_rate.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "contract renewal schedule", "auto renewal", "termination notice period", "contract schedule" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_LIFECYCLE_SCHEDULE" ], "related": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.CONTRACT_LIFECYCLE" ], "context": "Renewal and termination schedule rules for a contract - renewal type (auto/manual), termination notice periods, and collection period windows. Linked to CONTRACT_LIFECYCLE_SCHEDULE_DETAIL for notice/offset/collection period specifics. Key columns: contract_id, renewal_type, schedule_end.", "domain": "accounting", "source": "schema-analysis", "priority": 1 }, { "terms": [ "payment allocation", "payment distribution", "payment debit credit" ], "targets": [ "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.PAYMENT_ALLOCATION" ], "related": [ "ROYALTY_ACCOUNTING.{{env}}.COMBINED_PAYMENTS_DBT", "ORCHARD_APP_REPORTING_V2.{{env}}_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT" ], "context": "Allocates payment amounts to contracts and payees with debit/credit status tracking. Records actual payment disbursements during the payment cycle. Key columns: account_id, contract_id, payee_id, currency_amount, currency_code, debit_credit_status.", "domain": "accounting", "source": "schema-analysis", "priority": 1 } ] }