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

# Resource Identities

> Canonical names for SQLBuild resources, selectors, state, and integrations.

SQLBuild resource identities use lowercase ASCII snake\_case. A name must start with a lowercase
letter, end with a lowercase letter or digit, and contain only lowercase letters, digits, and
underscores. Consecutive underscores are valid, so established names such as
`race__mart_v_entry` remain canonical.

This contract applies to models, seeds, sources, SQL and Python functions, generic and singular
audits, attached audit definitions and instance names, SQL tests and parameterized cases,
scenarios, SQL and Python hooks, macros, model schemas, enums, constants, materializations,
providers, event exporters, loaders, tasks, assets, and checks. Private scoped declarations use
exactly one leading underscore, such as `_country_codes`; public declarations must not use a
leading underscore.

Provider classes are the one conventional derivation: when `provider_name` is omitted,
`AnalyticsApiProvider` resolves to `analytics_api_provider`. An explicit `provider_name` is an
authored identity and must already be canonical snake\_case; SQLBuild does not normalize it.

Names derived from files use the filename stem. For example, `models/daily_orders.sql` defines
the model identity `daily_orders`, while `audits/generic/expression_is_true.sql` defines the
generic audit identity `expression_is_true`. Directories organize resources but do not change
their names.

Physical warehouse identifiers are separate from SQLBuild resource identities. Database, schema,
table, model alias, column, tag, group, and directory names retain their existing adapter-specific
contracts and do not need to follow this profile.

## Invalid names

Compilation fails during discovery with `D016` when an authored identity is not canonical:

```text theme={null}
error[D016]: Invalid model identity 'DailyOrders' in models/DailyOrders.sql;
use snake_case 'daily_orders'
```

SQLBuild suggests a corrected spelling but never silently normalizes an identity. Silent
normalization would make selectors, manifests, persisted execution state, and integration keys
disagree about which resource ran.

## Migrating existing projects

1. Rename file-derived resources and explicit `name` values to snake\_case.
2. Update `__ref`, `__seed`, `__source`, function, hook, macro, audit, test, and dependency
   references.
3. Update selectors and external integrations, including Dagster asset/check keys, that use the
   old identity.
4. Compile before building.

A rename intentionally creates a new resource identity. Existing fingerprints, audit history,
and other persisted state under the old name are not silently reassigned to the new resource.