# Per-table / per-column human descriptions for the BIRD `financial` schema
# (PKDD'99 Czech bank). The text-to-SQL tool prepends the relevant subset to
# the LLM prompt so it can disambiguate cryptic column names like A2, A3, etc.

schema: financial

tables:
  account:
    description: One row per bank account. The pivot table — most facts hang off account_id.
    columns:
      account_id: Surrogate primary key for the account.
      district_id: Geographic district the account belongs to (joins to district).
      frequency: Statement issuance frequency. "POPLATEK MESICNE" = monthly, "POPLATEK TYDNE" = weekly, "POPLATEK PO OBRATU" = on transaction.
      date: Date the account was opened (YYMMDD as integer).

  client:
    description: One row per bank customer.
    columns:
      client_id: Surrogate primary key for the client.
      gender: '"M" or "F". Derived from birth_number.'
      birth_date: Date of birth, normalised. Original birth_number encoded gender by adding 50 to the month field for women.
      district_id: District the client lives in (joins to district).

  disp:
    description: Disposition — many-to-many link between client and account. Type tells you whether the client is the OWNER or just a USER of the account.
    columns:
      disp_id: Surrogate key.
      client_id: Joins to client.
      account_id: Joins to account.
      type: '"OWNER" or "DISPONENT" (USER). Only owners can request loans / cards.'

  district:
    description: Demographic and economic data for each Czech district. The A-columns are infamous — most analysis questions referencing demographics use these.
    columns:
      district_id: Surrogate key.
      A2: District name.
      A3: Region (a grouping of districts).
      A4: Number of inhabitants.
      A5: Number of municipalities with population < 499.
      A6: Number of municipalities with population 500-1999.
      A7: Number of municipalities with population 2000-9999.
      A8: Number of municipalities with population > 10000.
      A9: Number of cities.
      A10: Ratio of urban inhabitants (percent).
      A11: Average salary (in CZK).
      A12: Unemployment rate in 1995 (percent). NULL means missing data.
      A13: Unemployment rate in 1996 (percent).
      A14: Number of entrepreneurs per 1000 inhabitants.
      A15: Number of crimes committed in 1995. NULL means missing data.
      A16: Number of crimes committed in 1996.

  loan:
    description: One row per loan granted to an account.
    columns:
      loan_id: Surrogate key.
      account_id: The account the loan was granted to.
      date: Loan grant date (YYMMDD as integer).
      amount: Total amount of the loan (CZK).
      duration: Loan duration in months.
      payments: Monthly payment (CZK).
      status: Loan status code. "A" = contract finished, no problems. "B" = contract finished, loan not paid (DEFAULT). "C" = running contract, payments on time. "D" = running contract, client in debt (AT RISK). Defaults are A,B finished or B,D paid-flag attached.

  card:
    description: One row per credit/debit card issued to a disposition.
    columns:
      card_id: Surrogate key.
      disp_id: The disposition (and via it, the account) the card belongs to.
      type: '"junior", "classic", or "gold".'
      issued: Date the card was issued.

  trans:
    description: Transaction history. Largest table by far (~1M rows). Every credit, debit, transfer.
    columns:
      trans_id: Surrogate key.
      account_id: The account the transaction belongs to.
      date: Transaction date (YYMMDD as integer).
      type: '"PRIJEM" (credit) or "VYDAJ" (debit).'
      operation: Mode of operation, e.g. "VKLAD" (cash credit), "VYBER" (cash withdrawal), "PREVOD Z UCTU" (transfer from another bank), etc.
      amount: Amount (CZK).
      balance: Account balance after the transaction.
      k_symbol: Characterisation of the payment. "POJISTNE" = insurance, "SLUZBY" = household, "UROK" = interest credited, "SANKC. UROK" = penalty interest, "SIPO" = household payment, "DUCHOD" = old-age pension, "UVER" = loan payment.
      bank: Counterparty bank code (only set for inter-bank transfers).
      account: Counterparty account number (only set for inter-bank transfers).

  "order":
    description: Standing payment orders (recurring debits). Note the table name collides with a SQL keyword and must be quoted.
    columns:
      order_id: Surrogate key.
      account_id: The originating account.
      bank_to: Recipient bank.
      account_to: Recipient account.
      amount: Order amount (CZK).
      k_symbol: Purpose, same vocabulary as trans.k_symbol.