> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Static

Status: In development.

The Static provider serves the CSV files of [static datasets](/datasets/static-datasets): tables of reference data,
like address labels, that you write yourself instead of extracting from a chain. It points at a directory in object
storage: a local directory, or an Amazon S3, Google Cloud Storage, or Azure Blob Storage bucket. It doesn't extract
anything: Amp reads the files where they are when you query them. And it has no network: datasets find it by its
routing token.

This page covers the provider. [Static Datasets](/datasets/static-datasets) covers the whole flow: placing the files,
writing the dataset's manifest, and querying it.

## Prerequisites

* A running Amp you can manage, like one in [Solo Mode](/running-amp/solo-mode).
* [`ampctl`](/clis/ampctl), which installs with Amp.
* A directory holding your CSV files, named after the routing token you'll use, like `labels` (see
  [Routing tokens](/providers/static#routing-tokens)). For a local directory, it must be on the machine `ampd` runs on. For a bucket,
  `ampd` needs credentials for it, in the environment it runs in (see [Credentials](/providers/static#credentials)), like these for
  S3:

  ```bash
  export AWS_ACCESS_KEY_ID=…
  export AWS_SECRET_ACCESS_KEY=…
  export AWS_REGION=us-east-1
  ```

## Configure the provider

A provider's configuration is a TOML file. A static provider's has two fields:

```toml [static_labels.toml]
kind = "static"
object_store_root = "file:///data/static/labels"
```

* `kind`: always `"static"`.
* `object_store_root`: the URL of the directory that holds the files. Its last path segment, `labels`, is the
  provider's routing token.

The same provider, for files in an S3 bucket:

```toml [static_labels.toml]
kind = "static"
object_store_root = "s3://my-bucket/reference/labels"
```

There's no `network`, and no field for credentials. The
[Provider Configuration Reference](/providers/configuration-reference#static) documents both fields.

## Register the provider

```bash
ampctl provider register static_labels ./static_labels.toml
```

A provider's name holds lowercase letters, digits, and underscores, and starts with a letter or an underscore.
Registering a provider under a name that exists replaces it. [Providers](/providers) covers registering, listing, and
removing providers.

Amp doesn't check the configuration or the files when you register the provider: mistakes show up when you query a
table it serves (see [Errors](/providers/static#errors)). There's nothing to deploy either: once you
[register a static dataset](/datasets/static-datasets) whose tables start with `labels`, you can query it.

## Routing tokens

A static provider's routing token is the last path segment of its `object_store_root`: `labels` in both examples
above, with or without a trailing `/`. Each table of a static dataset has a `path`, whose first segment is a routing
token. When you query the table, Amp finds the static provider with that token, and reads the file at the provider's
`object_store_root`, followed by the rest of the path:

| Table `path`                  | Provider's `object_store_root`    | File Amp reads                                    |
| ----------------------------- | --------------------------------- | ------------------------------------------------- |
| `labels/eth_block_labels.csv` | `file:///data/static/labels`      | `/data/static/labels/eth_block_labels.csv`        |
| `labels/2024/prices.csv`      | `s3://my-bucket/reference/labels` | `s3://my-bucket/reference/labels/2024/prices.csv` |

* **Exact matches**: tokens match exactly, uppercase and lowercase included.
* **A path is required**: `object_store_root` needs a path, since its last segment is the token. `s3://my-bucket`
  alone has none.
* **Moving files**: a dataset only names the token, so you can move its files, like from a local directory to a
  bucket, by registering the provider again with a new `object_store_root` that ends with the same segment.
* **One provider per token**: when two static providers share a token, Amp uses the first by name, and logs a warning.
  Give each provider its own token.

The provider's name never appears in queries: they name the dataset and the table, like any other.

## Credentials

The files stay in your object store, and Amp reads them in place, with credentials from the environment `ampd` runs in,
not from the provider's configuration. Only queries read static datasets (see
[Static Datasets](/datasets/static-datasets#limitations)), so set the credentials for every `ampd` that serves
queries, then restart it.

| Scheme                                                  | Store                                     | Credentials                                                                                                    |
| ------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `file://`                                               | A directory on the machine `ampd` runs on | None: the user `ampd` runs as must be able to read the files                                                   |
| `s3://`, or `s3a://`                                    | Amazon S3, or an S3-compatible store      | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`, plus `AWS_ENDPOINT` for an S3-compatible store |
| `gs://`                                                 | Google Cloud Storage                      | `GOOGLE_APPLICATION_CREDENTIALS`, the path of a service account's key file, or other `GOOGLE_*` variables      |
| `az://`, or `adl://`, `azure://`, `abfs://`, `abfss://` | Azure Blob Storage                        | `AZURE_STORAGE_ACCOUNT_NAME`, plus the account's access key or a SAS token, in `AZURE_*` variables             |

Without credentials for S3, Amp asks the machine it runs on for them, like an EC2 instance for its role. Elsewhere, a
query fails after about 15 seconds, with an error that includes
`Error performing PUT http://169.254.169.254/latest/api/token`. [Storage](/running-amp/storage#object-storage) lists
every variable of each store.

## Limitations

* **CSV only**: a static provider serves CSV files, not Parquet, JSON, or other formats.
* **No HTTP**: `object_store_root` can't be an `http://` or `https://` URL.
* **No change tracking**: Amp reads the files at each query, so a query sees a file's latest content, but nothing
  tells a client that a file changed.

## Errors

### ``no `static` provider matches routing token `labels` ``

A query reads a table whose path starts with `labels`, and no static provider has that token. Either none is
registered (list them with `ampctl provider list`), its `object_store_root` ends with another segment, or Amp can't
read its `object_store_root`, like one without a path or with an unsupported scheme. Register the provider again with
a valid `object_store_root` that ends with the token.

### `failed to construct object store for static provider 'static_labels'`

Amp couldn't set up access to the provider's store, like when settings the scheme needs are missing from its
environment: an `az://` root without `AZURE_STORAGE_ACCOUNT_NAME` ends the message with `Account must be specified`.
Set them where `ampd` runs (see [Credentials](/providers/static#credentials)), and restart `ampd`.

### ``no usable `static` provider for routing token 'labels': provider 'static_labels': …``

The provider's configuration refers to an environment variable, like `${LABELS_BUCKET}`, that isn't set where `ampd`
runs. Set it, and restart `ampd`.

### `Object at location … not found`

There's no file where the provider's `object_store_root` and the table's `path` point. Check both, and that the file
exists. When the store answers with another error instead, like `403 Forbidden`, the credentials `ampd` has can't read
the file.