Understanding table and field references in the Analytics model

Last updated: November 19, 2026

Overview

If you write SQL in a custom report, or look at how a field is defined behind one of your Analytics reports, you may have noticed two pieces of syntax that both look like they point at a table, but that do very different jobs.

schema: PRODUCT
table_name: PRODUCT

sql: ${product__product.name}

This article covers what each one means, why they can look alike, how to tell them apart at a glance, and which one to use when you write your own SQL.

The two syntaxes

Both appear in the same model files, but they live in different places and resolve to different things.

Table reference, using schema and table_name

This pair appears once, near the top of a view's definition. It is what actually connects that view to a real table in your database.

schema: NOTIFICATION
table_name: ATTACHMENT

Everything else in that view, meaning its fields, filters, and calculations, reads from whatever table this points to. Each view that reads straight from a database table declares this pair once. Fields added on top of a view, in a topic or a report, don't repeat it.

Field reference, using ${view_name.field_name}

This shows up inside a field's own definition, wrapped in ${ }.

measures:
  active_count:
    sql: ${account__account.id}
    aggregate_type: count_distinct

This does not point to a table. It points to a field that has already been defined somewhere else in the model, in this example the id field on the view named account__account. When a report runs, that reference is swapped out for the real, underlying SQL of that field.

You will see this same syntax used to combine fields from two different views into one calculation, or to reuse a field's logic instead of redefining it.

Why they are easy to mix up

Views are conventionally named after the table they represent, with the schema and table name joined together, like product__product. That naming convention is exactly why a field reference such as the one below can look like a table pointer at first glance.

${product__product.name}

It is not one. Here, product__product is only the name of a view you are borrowing a field from. That view's actual table binding is declared separately, with schema: and table_name:, wherever the view is originally defined.

Quick way to tell them apart

Looks like

Is it

What it does

schema: X / table_name: Y

Table reference

Binds a view to a real database table

${view_name.field_name}

Field reference

Reuses another view's already defined field

If you cannot tell which table a report ultimately reads from just by looking at a ${...} reference, that is expected. You would need to look up where view_name is originally defined to find its schema: and table_name: pair.

Writing SQL in a custom report

When you start a custom report with SQL, your query runs directly against the database and bypasses the Analytics model. Refer to tables by their database name, SCHEMA.TABLE, rather than by a view name.

  • Write a complete query, with both a SELECT and a FROM clause.

  • Every table you select a column from must be in the FROM clause or joined to it.

  • To find the database name behind a field reference, split the view name on the double underscore: the first part is the schema and the second is the table. For example, ${product__product.name} reads the NAME column of the PRODUCT.PRODUCT table.

SELECT p.NAME, p.TYPE
FROM PRODUCT.PRODUCT AS p

Some fields are calculations rather than columns, so their name doesn't match a column in the table. To build a report from those fields, start from a Topic instead of SQL. See Creating custom reports and dashboards.

Still not sure?

If you are troubleshooting a report and want to confirm exactly which table a value traces back to, reach out to gaiia support with the report or view name. We are happy to trace it for you.