> ## 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.

> ## Agent Instructions
> To query the Token Terminal data catalog, read https://tokenterminal.com/docs/catalog/agents-manual.md first. It is the whole catalog as one page: table naming grammar, key columns, partition and cluster rules, units, additivity, and the tables that are documented but not served yet.
> Never query a catalog table on a time bound alone. Also filter its cluster key, which you read from INFORMATION_SCHEMA.COLUMNS; an empty result means the object is a view, whose pruning contract is on its page. Compute is billed to the caller's own Google Cloud project.

# 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

**Metric definitions**

`dimensions.metrics` holds one row per measure per kind of thing measured, and each row says what unit the measure 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](https://tokenterminal.com/docs/catalog/assets/senders.md) 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>`metric_id`</td>
      <td>`STRING`</td>
      <td>Identifier of the measure, including the kind of thing it measures.</td>
    </tr>

    <tr>
      <td>`entity_id`</td>
      <td>`STRING`</td>
      <td>Kind of thing the measure is defined for: an asset, a project, a chain.</td>
    </tr>

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

    <tr>
      <td>`column_name`</td>
      <td>`STRING`</td>
      <td>Column the measure's value sits in.</td>
    </tr>

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

    <tr>
      <td>`generic_definition`</td>
      <td>`STRING`</td>
      <td>What the measure means, whatever it is measuring.</td>
    </tr>

    <tr>
      <td>`ai_hint`</td>
      <td>`STRING`</td>
      <td>Guidance for software reading the table on how to use the measure.</td>
    </tr>

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

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

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

    <tr>
      <td>`measure_type`</td>
      <td>`STRING`</td>
      <td>`flow`, `balance`, `ratio` or `unique_count`.</td>
    </tr>

    <tr>
      <td>`additivity`</td>
      <td>`STRING`</td>
      <td>`additive`, `semi_additive` or `non_additive`.</td>
    </tr>

    <tr>
      <td>`value_grain`</td>
      <td>`STRING`</td>
      <td>The level the value is measured at.</td>
    </tr>

    <tr>
      <td>`over_time`</td>
      <td>`STRING`</td>
      <td>What to do when turning several days into one figure.</td>
    </tr>

    <tr>
      <td>`across_dimensions`</td>
      <td>`STRING`</td>
      <td>What to do when turning several things into one figure.</td>
    </tr>

    <tr>
      <td>`ranking_direction`</td>
      <td>`STRING`</td>
      <td>Which end of a ranking counts as better.</td>
    </tr>

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

    <tr>
      <td>`formula_expression`</td>
      <td>`STRING`</td>
      <td>The formula, where the measure is worked out from others.</td>
    </tr>

    <tr>
      <td>`formula_dependencies`</td>
      <td>`ARRAY<STRING>`</td>
      <td>Measures the formula reads.</td>
    </tr>

    <tr>
      <td>`formula_summary`</td>
      <td>`STRING`</td>
      <td>The formula in words.</td>
    </tr>

    <tr>
      <td>`methodology_summary`</td>
      <td>`STRING`</td>
      <td>How the measure is worked out.</td>
    </tr>

    <tr>
      <td>`source_types`</td>
      <td>`ARRAY<STRING>`</td>
      <td>Kinds of source the measure comes from.</td>
    </tr>

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

    <tr>
      <td>`notes`</td>
      <td>`ARRAY<STRING>`</td>
      <td>Additional notes.</td>
    </tr>

    <tr>
      <td>`quality_minimum`</td>
      <td>`FLOAT64`</td>
      <td>Lowest value considered plausible.</td>
    </tr>

    <tr>
      <td>`quality_maximum`</td>
      <td>`FLOAT64`</td>
      <td>Highest value considered plausible.</td>
    </tr>

    <tr>
      <td>`inserted_at`</td>
      <td>`TIMESTAMP`</td>
      <td>When the row was published.</td>
    </tr>
  </tbody>
</table>

**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>`metric_id`</td>
      <td>`STRING`</td>
      <td>Measure the definition applies to.</td>
    </tr>

    <tr>
      <td>`entity_id`</td>
      <td>`STRING`</td>
      <td>Kind of thing it applies to: an asset, a project, a chain.</td>
    </tr>

    <tr>
      <td>`entity_ref`</td>
      <td>`STRING`</td>
      <td>The specific thing, for example `usdc`.</td>
    </tr>

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

## Sample queries

**By entity**

**List every measure defined for one kind of thing, 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 entity_id = 'asset'
  and not deprecated
order by measure
```

**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
```

**Definitions and sources**

**Read every project measure with its written definition, its combination rules and the kinds of source behind it.** `generic_definition` is the wording published for the measure, and `source_types` names what the number is built from, so a reader can tell an onchain measure from one built on something else without leaving the table. Together with `additivity`, `over_time` and `across_dimensions` this is the whole contract for a measure in one row.

```sql theme={null}
select
    metric_id,
    title,
    unit,
    additivity,
    over_time,
    across_dimensions,
    source_types,
    generic_definition
from `dimensions.metrics`
where entity_id = 'project'
  and not deprecated
order by metric_id
```

**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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.