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

# Constants

> Define reusable compiler-validated values and reference them safely from SQL.

Constants give a name to a value used in SQL. SQLBuild validates the value during compilation and
asks the active adapter to render it safely for its SQL dialect. Constant values are data, never raw
SQL snippets.

## Create a constant

Put project-wide constants under the top-level `constants/` directory. Files are discovered
recursively, and one file may contain more than one declaration.

```text theme={null}
my_project/
├── constants/
│   ├── market/
│   │   └── thresholds.sql
│   └── reporting_day.sql
├── models/
└── sqlbuild_project.toml
```

```sql theme={null}
-- constants/market/thresholds.sql
CONSTANT (name min_runners, value 7);
CONSTANT (name fallback_source, value "centrum");
CONSTANT (name enabled, value true);
CONSTANT (name ratio, value 0.75);
CONSTANT (name missing_value, value null);
```

Folders below `constants/` are organizational. They do not change where project-wide constants are
available.

## Use a constant

Reference a constant with `@const("name")`:

```sql theme={null}
SELECT *
FROM prices
WHERE runner_count >= @const("min_runners")
  AND source = @const("fallback_source")
```

References work in model queries, SQL hooks, SQL functions, audits, unit tests, scenarios, and
inline source expressions. An unknown constant fails compilation.

## Scalar values

Constants support strings, signed integers, booleans, finite floating-point numbers, exact
decimals, and `null`. Integers use a portable signed 64-bit range. `NaN` and positive or negative
infinity are rejected.

Use `type decimal` with a quoted value when decimal precision must be exact:

```sql theme={null}
CONSTANT (
  name usd_rate,
  type decimal,
  value "2.4700",
);
```

SQLBuild parses the quoted value directly as a decimal rather than first converting it to a binary
float. An incompatible `type` and `value` fails compilation.

## Naming rules

Public constant names must be unique among public constants and cannot begin with `_`. Enum,
constant, and macro names use separate namespaces, so an enum and a constant may share a name.

## More constant features

<CardGroup cols={2}>
  <Card title="Collections and Rendering" icon="layer-group" href="/concepts/constants/collections-and-rendering">
    Define lists, sets, and objects, then choose value-list or native-array rendering.
  </Card>

  <Card title="Model-Private Values" icon="lock" href="/concepts/model-private-values">
    Keep a constant inside one model when no other resource should use it.
  </Card>
</CardGroup>

To limit a constant to one folder, or to that folder and its child folders, see
[Declarations and Scopes](/concepts/declaration-scopes).