Naming Conventions Cheatsheet
Quick reference for naming every object in your medallion architecture.
The Golden Rules
┌──────────────────────────────────────────────────────────────────────────────────┐
│ │
│ 1. Everything is snake_case (no camelCase, no PascalCase, no UPPER_CASE) │
│ 2. Use full words (customer_id, not cust_id or c_id) │
│ 3. No prefixes on columns (id, not tbl_orders_id) │
│ 4. Singular table names (order, not orders) — OR plural, but be consistent │
│ 5. System columns start _ (_ingested_at, _source_file) │
│ 6. No abbreviations (transaction, not txn; quantity, not qty) │
│ 7. Boolean columns: is_/has_ (is_active, has_subscription) │
│ 8. Date columns: *_date (order_date, not order_dt) │
│ 9. Timestamp columns: *_at (created_at, updated_at) │
│ 10. Foreign keys match source (customer_id in orders = customer_id in customers) │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
Catalog Naming
Pattern: {environment}_{layer}
┌─────────────────┬─────────────────────────────────────────────────────────────┐
│ Environment │ Catalogs │
├─────────────────┼─────────────────────────────────────────────────────────────┤
│ Production │ prod_bronze prod_silver prod_gold │
│ Staging │ stg_bronze stg_silver stg_gold │
│ Development │ dev_bronze dev_silver dev_gold │
│ Sandbox │ sandbox_bronze sandbox_silver sandbox_gold │
├─────────────────┼─────────────────────────────────────────────────────────────┤
│ Alternative: │ bronze silver gold │
│ (single env) │ (no env prefix when only prod exists) │
└─────────────────┴─────────────────────────────────────────────────────────────┘
Schema Naming
Pattern: {business_domain}
┌──────────────────────────────────────────────────────────────────────────────────┐
│ │
│ Good: sales, marketing, finance, product, logistics, hr, support │
│ Bad: src_sales, dbo, raw_data, staging, temp │
│ │
│ Special schemas (prefixed with underscore): │
│ _ops — pipeline metrics, ingestion logs, health checks │
│ _quarantine — rejected/failed rows (silver layer only) │
│ _audit — access logs, change tracking │
│ │
│ Full path examples: │
│ prod_bronze.sales.orders │
│ prod_silver.marketing.campaigns │
│ prod_gold.analytics.daily_revenue │
│ prod_silver.sales._quarantine │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
Table Naming
┌────────────────────┬──────────────────────────────────────────────────────────────┐
│ Table Type │ Naming Pattern │
├────────────────────┼──────────────────────────────────────────────────────────────┤
│ Fact tables │ {entity}_{event} → order_items, payment_transactions │
│ Dimension tables │ {entity} → customers, products, stores │
│ Bridge/junction │ {entity1}_{entity2}→ order_products, user_roles │
│ Aggregate tables │ {period}_{metric} → daily_revenue, monthly_active_users │
│ Snapshot tables │ {entity}_snapshot → inventory_snapshot │
│ SCD Type 2 │ {entity}_history → customers_history │
│ Staging tables │ _stg_{entity} → _stg_orders (temporary, drop after) │
│ Quarantine tables │ _quarantine_{src} → _quarantine_orders │
│ Feature tables │ {entity}_features → customer_features │
│ Views │ v_{name} → v_active_customers (optional prefix) │
│ Materialized views │ mv_{name} → mv_daily_revenue │
│ Ops/metadata tables │ _pipeline_metrics → _pipeline_metrics, _ingestion_log │
└────────────────────┴──────────────────────────────────────────────────────────────┘
Column Naming
┌────────────────────────────┬─────────────────────────────────────────────────────┐
│ Column Type │ Naming Pattern + Examples │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ Primary key │ {table_singular}_id → order_id, customer_id │
│ Foreign key │ {ref_table}_id → customer_id (matches PK) │
│ Natural/business key │ {entity}_{key_type} → product_sku, employee_code │
│ Boolean │ is_{state} / has_{x} → is_active, has_discount │
│ Date │ {event}_date → order_date, birth_date │
│ Timestamp │ {event}_at → created_at, updated_at │
│ Amount/money │ {thing}_amount → order_amount, tax_amount │
│ Count │ {thing}_count → item_count, retry_count │
│ Percentage/rate │ {thing}_rate / _pct → discount_rate, churn_pct │
│ Status/state │ {thing}_status → order_status │
│ Name (human) │ {part}_name → first_name, last_name │
│ Name (entity) │ {entity}_name → product_name, store_name │
│ Description │ {entity}_description → product_description │
│ Code/type │ {thing}_code / _type → currency_code, event_type │
│ URL │ {thing}_url → profile_url, image_url │
│ System/metadata │ _{name} → _ingested_at, _source_file │
│ Hash/checksum │ {thing}_hash → row_hash, content_hash │
└────────────────────────────┴─────────────────────────────────────────────────────┘
Tags
┌────────────────────────────┬─────────────────────────────────────────────────────┐
│ Tag Key │ Values + Purpose │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ layer │ bronze / silver / gold │
│ environment │ dev / staging / prod │
│ domain │ sales / marketing / finance / product │
│ data_owner │ team name (sales_team, data_platform) │
│ pii │ true / false │
│ retention_days │ 30 / 90 / 365 / unlimited │
│ sla_freshness │ 5min / 15min / 1hour / daily │
│ classification │ public / internal / confidential / restricted │
│ managed_by │ pipeline name or tool │
│ cost_center │ department or project code │
│ quality_tier │ raw / validated / certified │
└────────────────────────────┴─────────────────────────────────────────────────────┘
Bad → Good Examples
┌──────────────────────────────┬──────────────────────────────────────────────────┐
│ BAD │ GOOD │
├──────────────────────────────┼──────────────────────────────────────────────────┤
│ tblOrders │ orders │
│ dbo.CustomerData │ silver.sales.customers │
│ fact_order_items_v2_final │ order_items │
│ cust_id │ customer_id │
│ CrtDt │ created_at │
│ order_dt │ order_date │
│ isActive │ is_active │
│ amt │ amount (or order_amount if ambiguous) │
│ txn_type │ transaction_type │
│ qty │ quantity │
│ Prod_Cat_Nm │ product_category_name │
│ CUSTOMER_EMAIL_ADDRESS │ email (or customer_email if ambiguous) │
│ temp_staging_orders_20250101 │ _stg_orders (drop after load) │
│ bronze_raw_src_sys1_orders │ bronze.sales.orders │
│ gold__final__v3_revenue │ gold.analytics.daily_revenue │
└──────────────────────────────┴──────────────────────────────────────────────────┘
File & Path Naming (ADLS / S3)
┌──────────────────────────────────────────────────────────────────────────────────┐
│ │
│ Storage account: {org}{env}datalake │
│ Container: {layer} │
│ Path: /{domain}/{table}/ │
│ Partition: {partition_col}={value}/ │
│ │
│ Examples: │
│ ────────── │
│ abfss://bronze@acmeproddatalake.dfs.core.windows.net/ │
│ sales/orders/_ingested_date=2025-01-15/part-00000.snappy.parquet │
│ │
│ abfss://silver@acmeproddatalake.dfs.core.windows.net/ │
│ sales/orders/order_date=2025-01-15/part-00000.snappy.parquet │
│ │
│ abfss://gold@acmeproddatalake.dfs.core.windows.net/ │
│ analytics/daily_revenue/revenue_date=2025-01-15/part-00000.snappy.parquet │
│ │
│ Checkpoints: │
│ abfss://checkpoints@acmeproddatalake.dfs.core.windows.net/ │
│ bronze/sales/orders/ │
│ silver/sales/orders/ │
│ │
└──────────────────────────────────────────────────────────────────────────────────┘
Notebook / Job Naming
┌────────────────────────────┬─────────────────────────────────────────────────────┐
│ Object Type │ Naming Pattern + Examples │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ Notebooks │ {layer}_{domain}_{table} │
│ │ bronze_sales_orders │
│ │ silver_sales_orders │
│ │ gold_analytics_daily_revenue │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ Workflows/Jobs │ job_{layer}_{domain}_{schedule} │
│ │ job_bronze_sales_continuous │
│ │ job_silver_sales_hourly │
│ │ job_gold_analytics_daily │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ Clusters │ {purpose}_{env}_{size} │
│ │ ingestion_prod_medium │
│ │ transform_prod_large │
│ │ analytics_prod_small │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ DLT Pipelines │ dlt_{domain}_{scope} │
│ │ dlt_sales_full │
│ │ dlt_marketing_campaigns │
├────────────────────────────┼─────────────────────────────────────────────────────┤
│ Service Principals │ sp_{purpose}_{env} │
│ │ sp_ingestion_prod │
│ │ sp_transform_prod │
│ │ sp_analytics_prod │
└────────────────────────────┴─────────────────────────────────────────────────────┘
Use the naming_convention_generator.py code example to auto-generate your catalog and schema setup SQL from these patterns.
This is 1 of 6 resources in the DataStack Pro toolkit. Get the complete [Medallion Architecture Guide] with all files, templates, and documentation for $19.
Or grab the entire DataStack Pro bundle (6 products) for $164 — save 30%.
Top comments (0)