> ## Documentation Index
> Fetch the complete documentation index at: https://tokenterminal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Metric definitions

> Every measure in the catalog, with its unit and the rules for combining it.

Some numbers you can add up and some you cannot. Fees for a week are the seven daily figures added together. Circulating supply for a week is not: add seven days of supply and you get a number seven times too big. Add up a count of distinct addresses and you count anyone who showed up on two days twice.

Two tables hold the rules.

* `dimensions.metrics`: one row per measure per kind of thing measured, with its unit and its combination rules.
* `dimensions.metric_instances`: one row per measure with a specific wording, for one entity.

## Tables

<Tabs>
  <Tab title="Metric definitions">
    `dimensions.metrics` holds one row per measure per kind of thing measured, and each row says which daily table the measure sits in, what unit it is in, and what to do with it when you combine days or combine things. The rows come from the same authored definitions the daily tables are built from, so the two never disagree.

    Two columns hold the answer to whether a measure sums. `over_time` says what to do when you turn several days into one figure. `across_dimensions` says what to do when you turn several things, such as several chains or apps, into one figure. `measure_type` names which of four kinds of number you are looking at, and `additivity` sums that up in a word.

    | `measure_type` | `additivity`    | Over time                 | Across things |
    | -------------- | --------------- | ------------------------- | ------------- |
    | `flow`         | `additive`      | `sum`                     | `sum`         |
    | `balance`      | `semi_additive` | `last_value`              | `sum`         |
    | `ratio`        | `non_additive`  | `average` or `last_value` | `unsupported` |
    | `unique_count` | `non_additive`  | `last_value`              | `unsupported` |

    A **flow** counts activity over a stretch of time, so it adds up freely in both directions: across days, and across the things being measured. Fees for a project are its apps' fees added together, just as fees for a week are seven days added together.

    A **balance** is a level: how much of something there was at the end of the day. Balances add up across things but never across days: the supply of USDC is its supply on each chain added together. For a range of days, take the last day's figure.

    A **ratio** is a rate, such as a yield. A **unique count** counts distinct addresses. Neither adds up, and both read `unsupported` across things because the daily table alone does not hold enough to combine them correctly. Averaging two yields needs to know how much money sits behind each, and the daily table does not carry that. Combining two counts of distinct addresses needs the addresses themselves, not the counts. [Assets ▸ Senders](/docs/catalog/assets/senders) shows how a count of distinct addresses widens.

    <table>
      <thead>
        <tr>
          <th width="280">Column</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>metric\_id</code></td>
          <td><code>STRING</code></td>
          <td>Identifier of the measure, including the kind of thing it measures.</td>
        </tr>

        <tr>
          <td><code>entity\_id</code></td>
          <td><code>STRING</code></td>
          <td>Kind of thing the measure is defined for: an asset, a project, a chain.</td>
        </tr>

        <tr>
          <td><code>measure</code></td>
          <td><code>STRING</code></td>
          <td>Name of the measure.</td>
        </tr>

        <tr>
          <td><code>column\_name</code></td>
          <td><code>STRING</code></td>
          <td>Column the measure sits in on its daily table.</td>
        </tr>

        <tr>
          <td><code>served\_by</code></td>
          <td><code>STRING</code></td>
          <td>Daily table the measure sits in.</td>
        </tr>

        <tr>
          <td><code>title</code></td>
          <td><code>STRING</code></td>
          <td>Display title.</td>
        </tr>

        <tr>
          <td><code>generic\_definition</code></td>
          <td><code>STRING</code></td>
          <td>What the measure means, whatever it is measuring.</td>
        </tr>

        <tr>
          <td><code>ai\_hint</code></td>
          <td><code>STRING</code></td>
          <td>Guidance for software reading the table on how to use the measure.</td>
        </tr>

        <tr>
          <td><code>unit</code></td>
          <td><code>STRING</code></td>
          <td>Unit of the value: <code>usd</code>, <code>count</code>, <code>ratio</code>, <code>pct</code>.</td>
        </tr>

        <tr>
          <td><code>format</code></td>
          <td><code>STRING</code></td>
          <td>How to display the value.</td>
        </tr>

        <tr>
          <td><code>deprecated</code></td>
          <td><code>BOOL</code></td>
          <td>Whether the measure is retired.</td>
        </tr>

        <tr>
          <td><code>measure\_type</code></td>
          <td><code>STRING</code></td>
          <td><code>flow</code>, <code>balance</code>, <code>ratio</code> or <code>unique\_count</code>.</td>
        </tr>

        <tr>
          <td><code>additivity</code></td>
          <td><code>STRING</code></td>
          <td><code>additive</code>, <code>semi\_additive</code> or <code>non\_additive</code>.</td>
        </tr>

        <tr>
          <td><code>value\_grain</code></td>
          <td><code>STRING</code></td>
          <td>The level the value is measured at.</td>
        </tr>

        <tr>
          <td><code>over\_time</code></td>
          <td><code>STRING</code></td>
          <td>What to do when turning several days into one figure.</td>
        </tr>

        <tr>
          <td><code>across\_dimensions</code></td>
          <td><code>STRING</code></td>
          <td>What to do when turning several things into one figure.</td>
        </tr>

        <tr>
          <td><code>ranking\_direction</code></td>
          <td><code>STRING</code></td>
          <td>Which end of a ranking counts as better.</td>
        </tr>

        <tr>
          <td><code>dimensions</code></td>
          <td><code>ARRAY\<STRING></code></td>
          <td>Ways the measure can be broken down.</td>
        </tr>

        <tr>
          <td><code>formula\_expression</code></td>
          <td><code>STRING</code></td>
          <td>The formula, where the measure is worked out from others.</td>
        </tr>

        <tr>
          <td><code>formula\_dependencies</code></td>
          <td><code>ARRAY\<STRING></code></td>
          <td>Measures the formula reads.</td>
        </tr>

        <tr>
          <td><code>formula\_summary</code></td>
          <td><code>STRING</code></td>
          <td>The formula in words.</td>
        </tr>

        <tr>
          <td><code>methodology\_summary</code></td>
          <td><code>STRING</code></td>
          <td>How the measure is worked out.</td>
        </tr>

        <tr>
          <td><code>source\_types</code></td>
          <td><code>ARRAY\<STRING></code></td>
          <td>Kinds of source the measure comes from.</td>
        </tr>

        <tr>
          <td><code>caveats</code></td>
          <td><code>ARRAY\<STRING></code></td>
          <td>Known limitations of the measure.</td>
        </tr>

        <tr>
          <td><code>notes</code></td>
          <td><code>ARRAY\<STRING></code></td>
          <td>Additional notes.</td>
        </tr>

        <tr>
          <td><code>quality\_minimum</code></td>
          <td><code>FLOAT64</code></td>
          <td>Lowest value considered plausible.</td>
        </tr>

        <tr>
          <td><code>quality\_maximum</code></td>
          <td><code>FLOAT64</code></td>
          <td>Highest value considered plausible.</td>
        </tr>

        <tr>
          <td><code>inserted\_at</code></td>
          <td><code>TIMESTAMP</code></td>
          <td>When the row was published.</td>
        </tr>
      </tbody>
    </table>
  </Tab>

  <Tab title="Metric instances">
    `dimensions.metric_instances` holds one row where a measure needs a more exact definition for one project or one asset than the general one gives. Revenue means something particular for a lending market and something else for an exchange.

    <table>
      <thead>
        <tr>
          <th width="280">Column</th>
          <th width="130">Type</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>metric\_id</code></td>
          <td><code>STRING</code></td>
          <td>Measure the definition applies to.</td>
        </tr>

        <tr>
          <td><code>entity\_id</code></td>
          <td><code>STRING</code></td>
          <td>Kind of thing it applies to: an asset, a project, a chain.</td>
        </tr>

        <tr>
          <td><code>entity\_ref</code></td>
          <td><code>STRING</code></td>
          <td>The specific thing, for example <code>usdc</code>.</td>
        </tr>

        <tr>
          <td><code>definition</code></td>
          <td><code>STRING</code></td>
          <td>What the measure means for that one thing.</td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>

## Sample queries

<Tabs>
  <Tab title="By table">
    **List every measure in one daily table, with the rules for combining it.**

    ```sql theme={null}
    select
        measure,
        column_name,
        title,
        unit,
        measure_type,
        additivity,
        over_time,
        across_dimensions
    from `dimensions.metrics`
    where served_by = 'metrics.assets_daily'
      and not deprecated
    order by measure
    ```
  </Tab>

  <Tab title="Non-summable">
    **Find the measures that must never be summed.**

    ```sql theme={null}
    select
        entity_id,
        measure,
        measure_type,
        across_dimensions
    from `dimensions.metrics`
    where across_dimensions != 'sum'
    order by entity_id, measure
    ```
  </Tab>

  <Tab title="Specific definition">
    **Read the specific definition of a measure, falling back to the general one.**

    ```sql theme={null}
    select
        metrics.metric_id,
        metrics.title,
        coalesce(instances.definition, metrics.generic_definition) as definition
    from `dimensions.metrics` as metrics
    left join `dimensions.metric_instances` as instances
        on instances.metric_id = metrics.metric_id
        and instances.entity_ref = 'usdc'
    where metrics.entity_id = 'asset'
    order by metrics.metric_id
    ```
  </Tab>
</Tabs>