# Introduction to metadata

**LIBSAFE Advanced** allows users to add metadata to any file, folder or data container preserved in the system. Functions can be used to automatically generate metadata on ingest or it can be added manually, or both.

Metadata can be used for searching (even using complex queries), or it can be exported or consumed by other systems. Metadata can be associated with the objects in the following ways:

* Manually, using the platform's Management Interface (for a single item or in bulk), 
* Loaded from a CSV, XML or JSON file, 
* Using the API, 
* Using the platform Functions (you can define code functions that will do rich and advanced extraction and processing to your metadata) or
* Using the platform's [Python library](https://public.docs.libnova.com/LIBSAFE%20Go/python/) in conjunction with a [Jupyter Notebook](/libsafe-advanced-manual/get-started/jupyter-notebooks.md).

## Add metadata using the Management Interface

### Add metadata for a single item manually

1. Locate the data container you would like to add metadata to using the **Containers menu** section or by searching. This guide assumes metadata is properly configured for the data container. See [Configuration\Metadata](/libsafe-advanced-manual/configuration/configure-metadata.md) for more details or [Working with data containers](/libsafe-advanced-manual/get-started/work-with-data-containers.md) to see how to create them.
2. Select **Check-in** in case you are not checked in the container, and you have the check-in/out enabled for the data container.
3. In the data container page, choose **Explore content**:

![](/files/-MguJem9scnyKEVC58L9)

1. **Right click** on the item **(file or folder)** you would like to add metadata to and select **Properties**
2. In the dialog, select the **Metadata** tab, and the metadata fields that are part of the metadata schema linked to your container are shown. You can add or remove metadata from them. When you have finished, do not forget to select **Save.**

![](/files/-Mgk3VJM9Noupflkmx8x)

### Add metadata to multiple items in bulk

It is possible to add metadata to multiple items at once.

1. Locate the data container you would like to add metadata to using the **Containers menu** section or by searching. This guide assumes metadata is properly configured for the data container. See [Configuration\Metadata](/libsafe-advanced-manual/configuration/configure-metadata.md) for more details or [Working with data containers](/libsafe-advanced-manual/get-started/work-with-data-containers.md) to see how to create them.
2. Select **Check-in** in case you are not checked in the container, and you have the check-in/out enabled for the data container.
3. In the data container page, choose **Explore content**:

![](/files/-MguJemCHxSGZak7aACC)

1. Select multiple items using your mouse to **click-and-drag a box around the files or folders** you want to select. You can also use **Ctrl** and **Shift** and use the **Select all**, **Select none** or **Invert selection** in the file browser top bar.

![](/files/-MguJemDYNFWC2hoy_NN)

You can also **filter the files** in the folder you are looking at by file name, for instance, for selecting all XML or JPG files:

![](/files/-MguJemE1eclkbiKBYgP)

1. When the items to which you want to apply metadata have been selected, select the Function **Bulk Metadata Editor** in your Functions side bar. If you have folders selected, the platform will also apply your metadata to the files contained in them:

![](/files/-Mgk4k98LpyRCFm2zON9)

## Using the API

{% hint style="warning" %}
When users are uploading files to the platform, search results may not show the new file for a while. Consider this in your code when you are uploading and immediately after the upload you need to search for the uploaded file or alter its metadata. See [Tips when working with the API.](/libsafe-advanced-manual/developers-guide/using-the-api.md)
{% endhint %}

{% hint style="info" %}
API examples here are just illustrative. Check the [API documentation](/libsafe-advanced-manual/developers-guide/using-the-api.md) for additional information and all available methods.
{% endhint %}

1. Sign in to the platform's Management Interface
2. Obtain your API key selecting your name and then **Access Methods:**

![](/files/-Mgu7YD9792fzo30O9EQ)

1. To change metadata for an item using the API, you need to know the **unique file identifier** (**File id)** for it. You can do that by using the API search methods. API for searching is rich on features and it accepts complex queries. 

In this guide we are going to search for the items matching a file name:

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request POST \
  --url "$your_platform_url/api/file/elastic" \
  --header "Authorization: Bearer $your_platform_api_key" \
  --data '{
  "must": [
    {
      "term": {
        "filename.keyword": "my_filename.txt"
      }
    },
    {
      "term": {
        "container_id": 100
      }
    }
  ]
}'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use:

* **url**: Your platform address
* **header**: Your API Token (add Bearer prefix)
* **filename.keyword**: The filename you are searching for
  * It is important to add ".keyword" to this field, to allow for exact matches. The platform will not provide accurate results for the "filename" field without the ".keyword"
* **container\_id**: (optional) The id of the container to filter by. 
  {% endhint %}

1. With your **unique file identifier** (**File id)** you can **list** your item's metadata:

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET \
  --url "$your_platform_url/api/file/<ID>/metadata" \
  --header "authorization: Bearer $your_platform_api_key"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use:

* **url**: Your platform address
* **ID**: The File ID from the previous step
* **header**: Your API Token (add Bearer prefix)
  {% endhint %}

Or you can **update** it: If you would like to set the metadata field **title** to "Letter 188/12", you can do it in the following way:

{% tabs %}
{% tab title="Curl" %}

```bash
    curl --request PUT \
    --url "$your_platform_url/api/file/1928913/metadata" \
    --header 'Content-Type: application/json' \
    --header "authorization: Bearer $your_platform_api_key" \
    --data '{
      "metadata": [
             {
                   "iecode": "title",
                   "value": "Letter 188/12",
                   "action": "replace"
             }
       ]
    }'
```

{% endtab %}
{% endtabs %}

You can also add **multiple** values to a descriptor by sending an array of values:

{% tabs %}
{% tab title="Curl" %}

```bash
    curl --request PUT \
    --url "$your_platform_url/api/file/1928913/metadata" \
    --header 'Content-Type: application/json' \
    --header "authorization: Bearer $your_platform_api_key" \
    --data '{
      "metadata": [
             {
                  "iecode": "dc.creator",
                  "value": ["Emmanuelle Charpentier", "Jennifer Doudna"],
                  "action": "replace"
             }
       ]
    }'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use:

* **url**: Your platform address
* **ID**: The File ID from the previous step
* **header**: Your API Token (add Bearer prefix)
* **iecode:** The metadata field to edit
* **value:** The metadata value to edit (string *or* array of strings)
* **action:** add or delete (will clear any value).
  {% endhint %}

{% hint style="warning" %}
**CAUTION:** If you include no action parameter **IN ANY** of the request parameters, **the platform will remove EVERY metadata field value from the object** and will just add the last one you included (not just the one you are including in your request). This is designed for the case in which you want to make a single query and replace every metadata field in the item.

This means that if the file has title="new dataset" and author="Mike" and you launch a method without specifying an action with author="David", the author will be set to "David", but the title will be removed.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.libnova.com/libsafe-advanced-manual/get-started/introduction-to-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.