# Add Metadata to Your Files

You can add metadata to your files. You can do this when you upload your files through REST API or <ProductShortName/> SDK, or in the platform UI for the files already uploaded. You can then use these metadata as search filters or to boost ranking and retrieval. Metadata acts like tags that help you find the right content.

***

## About This Task

### File and Document Metadata

You can add metadata to both files and documents. Documents are text chunks created by indexing files. They're what query pipelines work with and what gets stored in the document store.

When you add metadata to a file, that metadata is automatically passed to the documents created from it during processing. You can preview file metadata in the Haystack Enterprise Platform or access it through the API.

Document metadata is stored in the document store, but it might not appear in the platform itself, especially for file types we don't support for preview. To view all metadata, use the API endpoints.

### Adding Metadata to Files

There are two ways to add metadata to your files:

- During upload: You upload metadata along with the actual files. You can use an API endpoint or the Python SDK to do this. When uploading a file, include a corresponding metadata file with the `meta.json` extension. For example, if you have a file called `myfile.pdf`, its metadata would be stored in a separate file called `myfile.pdf.meta.json`. This approach ensures the metadata is associated with the correct file.
- Update files already uploaded. You can do it through REST API or <ProductShortName/> platformUI:
  - Use the [Update File Meta](/docs/api/main/update-file-meta-api-v-1-workspaces-workspace-name-files-file-id-meta-patch.api.mdx) endpoint. 
  - Update the file metadata directly on the Files page in <ProductName/>. You can add, edit, and delete metadata for each file. 

### Adding Metadata to Documents

You can add metadata to documents by automatically labelling uploaded files with an LLM by using [LLMMetadataExtractor](/docs/reference/pipeline-components/data-processing/extract/LLMMetadataExtractor.mdx) in your index. Check the _AI-Generated-Metadata-for-Files_ index template. For detailed instructions and examples, see [Tutorial: Automatically Tagging Your Data with an LLM](/docs/tutorials/learn-the-basics/tutorial-automatically-tagging-your-data-with-an-llm.mdx).

## Metadata Format

Metadata is always a dictionary in this format: `{"meta_key1": "value", "meta_key2": "value2"}`. The value for a specific key in a _key:value_ pair must be of the same type across all files. For example, if one file has a key called "category" and its value is of type _string _`{"category":"news"}`, then the values of "category" in all other metadata files must also be strings. An upload will fail if another metadata file lists "category" with a value that's not a string but an integer or some other type.

:::info Enforcing Metadata Type
You can specify the metadata type by including a type suffix in the key, using the `_type` format. For example, `{ "datefield_text": "today" }` sets the metadata value as a string.

Use `_text` to define a metadata field as a string. This type is the most flexible—it includes all other types—so you can use it in any situation. However, if you apply `_text` to a field that normally holds a date range, you won’t be able to filter by date in your searches. In that case, <ProductShortName /> will treat the value as plain text rather than as a date range.
:::

:::warning 📢 Important

Do not use "`id`" or "`_id`" as metadata keys or values, as they're reserved for internal processing of <ProductName/>. If you add them, they'll be overwritten or rejected.
:::

### Formatting Guidelines for Uploading with SDK

When uploading with SDK, include one metadata file for each file you're uploading. The name of the metadata file should match the original file's name, but with a `meta.json` extension. Format the metadata inside the metadata file like this: `{"meta_key1": "value", "meta_key2": "value2"}`.

<details>

<summary> Example metadata file </summary>

This file contains reviews for the Hotel Park Royal Palace in Vienna. The file is called _austria_trend_hotel_park_royal_palace_vienna_0.txt_.

```Text austria_trend_hotel_park_royal_palace_vienna_0.txt
Positives:
location and how clean it is

Negatives:
lack of variety in food any thing you ask for will charge you 5 euro the WiFi is not covering all my room dogs are allowed
```

This is the accompanying metadata file. It's called _austria_trend_hotel_park_royal_palace_vienna_0.txt.meta.json_. 

```json austria_trend_hotel_park_royal_palace_vienna_0.txt.meta.json
{"Hotel_Address": "Schlossallee 8 14 Penzing 1140 Vienna Austria", "Review_Date": "2016-02-22", "Average_Score": 8.8, "Hotel_Name": "Austria Trend Hotel Park Royal Palace Vienna", "Reviewer_Score": 9.6}
```

</details>

### Formatting Guidelines for Uploading with REST API

If you're uploading files through the API, pass metadata for each file in a separate dictionary formatted like this: `meta={"key1":"value1", "key2":"value2"}`. For each file you're uploading, provide a corresponding metadata dictionary. The order matters: the first dictionary you pass is linked to the first file, the second dictionary to the second file, and so on. 

### Allowed Values

In your metadata dictionaries, you can pass the following:

- Numerical data
- Dates
- Keyword fields
- Lists

Metadata limitations:

- One level of nesting works best.
- The size limit for a single value in the _key:value_ pair is 32 766 bytes, which is roughly 32 766 characters.
- The total size of metadata (all keys and values) is 250 000 bytes maximum, roughly 250 000 characters.

### Example

Here are simple examples of metadata:

<Tabs>
  <TabItem value="python" label="Python">
  
  ```python
  metadata = [{"type": "article", "source": "New York Times", "title": "Leaders Look into the Future", "year published": "2020"}]
  ```

  </TabItem>
  <TabItem value="curl" label="cURL">
  
  ```curl
  {
    "type": "book",
    "topic": "business",
    "author": "Ben Horowitz",
    "book_titles": [
      "The Hard Thing About Hard Things",
      "What You Do Is Who You Are"
    ]
 } 
  ```

  </TabItem>
</Tabs>

## Add Metadata with the Python SDK

The easiest way is to upload metadata together with your files. For detailed instructions, see [Tutorial: Uploading Files with CLI](/docs/tutorials/learn-the-basics/tutorial-uploading-files-with-cli.mdx) or [Tutorials: Uploading Files with Python Methods](/docs/tutorials/learn-more-advanced-features/tutorial-uploading-files-with-python-methods.mdx).

## Add Metadata with REST API

Here's the code you can use to add metadata to files when [uploading them through REST API](/docs/api/main/upload-file-api-v-1-workspaces-workspace-name-files-post.api.mdx):

```curl
curl --request POST \
     --url 'https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/files?write_mode=OVERWRITE' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form file=@<YOUR_FILE.PDF>
		// Here is where you define the metadata for your file:
     --form 'meta={"year":"2009", "type":"financial report"}'
```

Make sure you update the following parameters:
- In the URL, update `<YOUR_WORKSPACE>` to your <ProductShortName/> workspace name.
- In the `authorization` header, replace `<YOUR_API_KEY>` with your <ProductShortName/> API key.
- In the `form` section:
    - Replace `<YOUR_FILE.PDF>` with the path to your file.
    - Update the metadata.

You can also add or update metadata of files that are already uploaded to <ProductName/>, using the [Update File Meta](/docs/api/main/update-file-meta-api-v-1-workspaces-workspace-name-files-file-id-meta-patch.api.mdx) endpoint. You need the ID of the file whose metadata you want to change. (You can check it with the [list files](/docs/api/main/list-files-api-v-1-workspaces-workspace-name-files-get.api.mdx) endpoint.)

```curl
curl --request PATCH \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/files/<FILE_ID>/meta \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     // Here is where you pass the metadata:
     --data '
{
     "year": "2009",
     "type": "financial report"
}
'
```

## Add Metadata from the UI

This is an easy way to add, update, and remove metadata from files.

1. Log in to <ProductName/> and go to **Files**. 
2. Find the file whose metadata you want to update, click **More actions** next to it, and choose **View Metadata**. 

    <ClickableImage
      src="/img/how-tos/metadata.png"
      alt="The View Metadata menu"
      size="standard"
    />

3. Update the metadata as needed. You must choose a type for every field and then add its key and value. When you're done, save your changes.
4. Continue for each file whose metadata you want to update.