> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentation for creating and configuring dictionaries
# CREATE DICTIONARY
export const CloudSupportedBadge = () =>
;
};
A dictionary is a mapping (`key -> attributes`) that is convenient for various types of reference lists.
ClickHouse supports special functions for working with dictionaries that can be used in queries. It is easier and more efficient to use dictionaries with functions than a `JOIN` with reference tables.
Dictionaries can be created in two ways:
* [With a DDL query](#creating-a-dictionary-with-a-ddl-query) (recommended)
* [With a configuration file](#creating-a-dictionary-with-a-configuration-file)
Creating a dictionary with a DDL query
Dictionaries can be created with DDL queries.
This is the recommended method because with DDL created dictionaries:
* No additional records are added to server configuration files.
* Dictionaries can be used like first-class entities such as tables or views.
* Data can be read directly, using familiar `SELECT` syntax rather than dictionary table functions. Note that when accessing a dictionary directly via a `SELECT` statement, cached dictionary will return only cached data, while for a non-cached dictionary it will return all the data that it stores.
* Dictionaries can be easily renamed.
Syntax
```sql theme={null}
CREATE [OR REPLACE] DICTIONARY [IF NOT EXISTS] [db.]dictionary_name [ON CLUSTER cluster]
(
key1 type1 [DEFAULT | EXPRESSION expr1] [IS_OBJECT_ID],
key2 type2 [DEFAULT | EXPRESSION expr2],
attr1 type2 [DEFAULT | EXPRESSION expr3] [HIERARCHICAL|INJECTIVE],
attr2 type2 [DEFAULT | EXPRESSION expr4] [HIERARCHICAL|INJECTIVE]
)
PRIMARY KEY key1, key2
SOURCE(SOURCE_NAME([param1 value1 ... paramN valueN]))
LAYOUT(LAYOUT_NAME([param_name param_value]))
LIFETIME({MIN min_val MAX max_val | max_val})
SETTINGS(setting_name = setting_value, setting_name = setting_value, ...)
COMMENT 'Comment'
```
| Clause | Description |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [Attributes](/reference/statements/create/dictionary/attributes) | Dictionary attributes are specified similarly to table columns. The only required property is the type, all others may have default values. |
| PRIMARY KEY | Defines the key column(s) for dictionary lookups. Depending on the layout, one or more attributes can be specified as keys. |
| [`SOURCE`](/reference/statements/create/dictionary/sources/overview) | Defines the data source for the dictionary (e.g. ClickHouse table, HTTP, PostgreSQL). |
| [`LAYOUT`](/reference/statements/create/dictionary/layouts/overview) | Controls how the dictionary is stored in memory (e.g. `FLAT`, `HASHED`, `CACHE`). |
| [`LIFETIME`](/reference/statements/create/dictionary/lifetime) | Sets the refresh interval for the dictionary. |
| [`ON CLUSTER`](/reference/statements/distributed-ddl) | Creates the dictionary on a cluster. Optional. |
| `SETTINGS` | Additional dictionary settings. Optional. |
| `COMMENT` | Adds a text comment to the dictionary. Optional. |
Creating a dictionary with a configuration file
Creating a dictionary with a configuration file is not applicable to ClickHouse Cloud. Please use DDL (see above), and create your dictionary as the `default` user.
The dictionary configuration file has the following format:
```xml theme={null}
An optional element with any content. Ignored by the ClickHouse server./etc/metrika.xml
```
You can configure any number of dictionaries in the same file.
Related content
* [Layouts](/reference/statements/create/dictionary/layouts/overview) — How dictionaries are stored in memory
* [Sources](/reference/statements/create/dictionary/sources/overview) — Connecting to data sources
* [Lifetime](/reference/statements/create/dictionary/lifetime) — Automatic refresh configuration
* [Attributes](/reference/statements/create/dictionary/attributes) — Key and attribute configuration
* [Embedded Dictionaries](/reference/statements/create/dictionary/embedded) — Built-in geobase dictionaries
* [system.dictionaries](/reference/system-tables/dictionaries) — System table with dictionary information