# Single Table Metadata

Use this guide to write a description for a single data table. In a single table, all your data is captured in a 2D format using rows and columns.

![This example of a single table includes a new row for each user. The row includes their personal information.](https://2284413265-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNLha4DaPNwVJ930KhmB%2Fuploads%2FvX1quRIf0O706j3Jbgzl%2Fsdmetrics-metadata-single-table-metadata_Mar%2010%202026.png?alt=media\&token=9ec4b11f-2580-4927-91cb-fafdbe02971e)

Your data description is called metadata. SDMetrics expects metadata as a **Python dictionary** object.

<details>

<summary>Click to see the table's metadata</summary>

This is the metadata dictionary for the illustrated table

```python
{
    "primary_key": "user_id",
    "columns": {
        "user_id": {
            "sdtype": "id",
            "regex_format": "U_[0-9]{3}"
        },
        "age": {
            "sdtype": "numerical"
        },
        "address": {
            "sdtype": "address",
            "pii": True
        }, 
        "tier": {
            "sdtype": "categorical"
        },
        "active": {
            "sdtype": "boolean"
        },
        "paid_amt": {
            "sdtype": "numerical"
        },
        "renew_date": {
            "sdtype": "datetime",
            "datetime_format": "%Y-%m-%d"
        }
    }
}
```

</details>

## Metadata Specification

The metadata has two keys:

* `"primary_key"`: the column name used to identify a row in your table. *For a composite primary key, provide a list of column names.*
* (required) `"columns"`: a dictionary description of each column

```python
{
    "primary_key": "user_id",
    "columns": { <column information> }   
}
```

### Column Information

Inside `"columns"`, you will describe each column. You'll start with the name of the column. Then you'll specify the type of data and any other information about it. There are specific data types to choose from. Expand the options below to learn about the data types.

{% tabs %}
{% tab title="boolean" %}
Boolean columns represent True or False values.

```python
"active": { 
    "sdtype": "boolean"
}
```

**Properties** (None)
{% endtab %}

{% tab title="categorical" %}
Categorical columns describe discrete data.

```python
"tier": {
    "sdtype": "categorical",
}
```

**Properties** (None)
{% endtab %}

{% tab title="datetime" %}
Date columns represent a point in time

```python
"renew_date": {
    "sdtype": "datetime",
    "format": "%Y-%m-%d"
}
```

**Properties**

* (required) `datime_format`: A string describing the format as defined by [Python's strftime module](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).

{% hint style="info" %}
The format string has special values to describe the components. For example, `Jan 06, 2022` is represented as `"%b %d, %Y".` Common values are:

* **Year**: `"%Y"` for a 4-digit year like 2022, or `"%y"` for a 2-digit year like 22
* **Month**: `"%m"` for a 2-digit month like 01, `"%b"` for an abbreviated month like Jan
* **Day**: `"%d"` for a 2-digit day like 06
  {% endhint %}
  {% endtab %}

{% tab title="numerical" %}
Numerical columns represents discrete or continuous numerical values.&#x20;

```python
"age": {
    "sdtype": "numerical"
},
"paid_amt": {
    "sdtype": "numerical",
    "compute_representation": "Float"
}
```

**Properties**

* `computer_representation`: A string that represents how you'll ultimately store the data. This determines the min and max values allowed\
  Available options are: `'Float'`, `'Int8'`, `'Int16'`, `'Int32'`, `'Int64'`, `'UInt8'`, `'UInt16'`, `'UInt32'`, `'UInt64'`
  {% endtab %}

{% tab title="id" %}
ID columns represent identifiers that do not have any special mathematical or semantic meaning

```python
"user_id": { 
    "sdtype": "id",
    "regex_format": "U_[0-9]{3}"
}
```

**Properties**

* `regex_format`: A string describing the format of the ID as a [regular expression](https://docs.python.org/3/library/re.html)
  {% endtab %}

{% tab title="other" %}
You can input any other data type such as `'phone_number'`, `'ssn'` or `'email'`. See the [Sdtypes Reference](https://docs.sdv.dev/sdv/reference/metadata-spec/sdtypes) for a full list.

```python
"address": {
    "sdtype": "address",
    "pii": True
}
```

**Properties**

* `pii`: A boolean denoting whether the data is sensitive
  * (default) `True`: The column is sensitive, meaning the synthetic data is anonymized&#x20;
  * `False`: The column is not sensitive, meaning the synthetic data may not be anonymized
    {% endtab %}
    {% endtabs %}

## Saving & Loading Metadata

After creating your dictionary, you can save it as a JSON file. For example, `my_metadata_file.json`.

```python
import json

with open('my_metadata_file.json', 'w') as f:
    json.dump(my_metadata_dict, f)
```

In the future, you can load the Python dictionary by reading from the file.

```python
import json 

with open('my_metadata_file.json') as f:
    my_metadata_dict = json.load(f)

# use my_metadata_dict in the SDMetrics library
```