From 7e4ca0e32979b094a816ac2d9bcd1e363b9ffc02 Mon Sep 17 00:00:00 2001
From: Jack Forgash <58153492+forgxyz@users.noreply.github.com>
Date: Tue, 29 Jul 2025 12:06:54 -0600
Subject: [PATCH] upd ez hourly prices doc (#517)

---
 models/docs/prices/prices.md                  | 28 ++++++++++++++++++-
 models/gold/price/price__ez_prices_hourly.yml | 12 ++++----
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/models/docs/prices/prices.md b/models/docs/prices/prices.md
index 8ab0d85..da5fb9f 100644
--- a/models/docs/prices/prices.md
+++ b/models/docs/prices/prices.md
@@ -18,7 +18,33 @@ A comprehensive fact table holding id and provider specific open, high, low, clo
 
 {% docs prices_ez_prices_hourly_table_doc %}
 
-A convenience table for determining token prices by address and blockchain, and native asset prices by symbol and blockchain. This data set is highly curated and contains metadata for one price per hour per unique asset and blockchain.
+## Description
+This table provides hourly price data for both native tokens and fungible tokens across multiple blockchain networks. The data combines curated token prices from external APIs like CoinGecko and CoinMarketCap into a unified view. Token addresses are normalized based on blockchain-specific conventions (e.g., IBC tokens and certain blockchains retain original case, while others are converted to lowercase). This table serves as the primary source for cross-chain price analysis and USD value calculations.
+
+## Key Use Cases
+- Cross-chain price comparison and analysis
+- USD value calculations for token transfers and DeFi transactions
+- Time-series price analysis and trend detection
+- Arbitrage opportunity identification across blockchains
+- Portfolio valuation and performance tracking
+- Bridge activity monitoring and cross-chain flow analysis
+- Token price volatility and market movement analysis
+
+## Important Relationships
+- Native blockchain assets are flagged by the boolean column `is_native` and tokens that have been verified by the Flipside team by the boolean column `is_verified`.
+- Used by `ez_token_transfers` and other ez_ tables for USD value calculations
+- Supports DeFi analytics through `ez_dex_swaps` and `ez_lending` tables
+- Enables cross-chain bridge analysis via `ez_bridge_activity` tables
+- Provides price context for NFT sales in `ez_nft_sales` tables
+
+## Commonly-used Fields
+- `hour`: Primary field for time-series analysis and trend detection
+- `token_address` and `blockchain`: Essential for identifying specific assets across chains
+- `price`: Critical for USD value calculations and financial analysis
+- `symbol` and `name`: Key for asset identification and reporting, however these columns have no uniqueness constraints and should not be used as the only identifier when filtering to a particular token price.
+- `is_native`: Important for distinguishing between native tokens and contract tokens
+- `is_imputed`: Critical for data quality assessment and low-liquidity token analysis
+- `is_verified`: Essential for filtering reliable token data and avoiding scams
 
 {% enddocs %}
 
diff --git a/models/gold/price/price__ez_prices_hourly.yml b/models/gold/price/price__ez_prices_hourly.yml
index bc278ec..f97eaaf 100644
--- a/models/gold/price/price__ez_prices_hourly.yml
+++ b/models/gold/price/price__ez_prices_hourly.yml
@@ -10,12 +10,14 @@ models:
         description: '{{ doc("prices_token_address") }}'
       - name: SYMBOL
         description: '{{ doc("prices_symbol") }}'
-      - name: BLOCKCHAIN
-        description: '{{ doc("prices_blockchain") }}'
+      - name: NAME
+        description: '{{ doc("prices_name") }}'
       - name: DECIMALS
         description: '{{ doc("prices_decimals") }}'
       - name: PRICE
         description: '{{ doc("prices_price") }}'
+      - name: BLOCKCHAIN
+        description: '{{ doc("prices_blockchain") }}'
       - name: IS_NATIVE
         description: '{{ doc("prices_is_native") }}'
       - name: IS_IMPUTED
@@ -24,9 +26,9 @@ models:
         description: '{{ doc("prices_is_deprecated") }}'
       - name: IS_VERIFIED
         description: '{{ doc("prices_is_verified") }}'
-      - name: EZ_PRICES_HOURLY_ID
-        description: '{{ doc("pk") }}'   
       - name: INSERTED_TIMESTAMP
         description: '{{ doc("inserted_timestamp") }}'   
       - name: MODIFIED_TIMESTAMP
-        description: '{{ doc("modified_timestamp") }}' 
\ No newline at end of file
+        description: '{{ doc("modified_timestamp") }}' 
+      - name: EZ_PRICES_HOURLY_ID
+        description: '{{ doc("pk") }}' 
\ No newline at end of file