> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-feat-updatereactquickstart.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilizing metadata

> Store descriptive information or data that provides additional context.

<Snippet file="shared/dxpbanner.mdx" />

## Overview

Metadata allows you to store and retrieve additional data about an Environment, Space, Record, or Field without
exposing it to end users.

## Environment-level

On the environment level `metadata` can be configured to record details about your current enivornment state. This can be useful for developers to store information about their deployments and even aggregate information about spaces, users, and data therein.

### Usage

Utilize `@flatfile/api` to create or update an Environment with metadata.

```jsx
await api.environments.update(environmentId, {
  metadata: {
    version: "0.0.0",
    deployedAt: new Date().toISOString(),
  },
});
```

## Space-level

The `metadata` object at the Space level is often used for details such as user ID, Space name, company ID, and company name.
Metadata can be added during Space creation or at a later stage.

<Info>
  Space-level metadata, while not visible in the user interface, can be utilized
  in all listeners.
</Info>

### Usage

Utilize `@flatfile/api` to create or update a Space with metadata.

```jsx
await api.spaces.update(spaceId, {
  metadata: {
    userId,
  },
});
```

Learn more about \[adding metadata in React embedded
[Flatfile](../apps/embedding/react/guide#spaceinfo).

## Workbook-level

The `metadata` object at the Workbook level is often used for details such as expirationDate.
Metadata can be added during Workbook creation or at a later stage.

<Info>
  Workbook-level metadata, while not visible in the user interface, can be
  utilized in all listeners.
</Info>

### Usage

Utilize `@flatfile/api` to create or update a Workbook with metadata.

```jsx
await api.workbook.update(spaceId, {
  metadata: {
    expirationDate,
  },
});
```

## Record-level

Customers often require a way to store extra computed or generated
information about a record that goes beyond what the data owner provides.

The `metadata` object on the record allows you to
include details like record IDs or reference IDs to other tables.

### Usage

Using the `@flatfile/plugin-record-hook` plugin, you can access and modify record-level metadata, similar to
how it works with normal field values. In this example, we will get the firstName from the record
and store the length of the name in metadata. This data will now be stored on the record itself.

<CodeGroup>
  ```jsx javascript
  listener.use(
    recordHook("contacts", (record) => {
      const firstName = record.get("firstName");

      record.setMetadata({
        firstNameLength: firstName?.length ?? 0,
      });

      return record;
    })
  );
  ```

  ```jsx typescript
  listener.use(
    recordHook("contacts", (record: FlatfileRecord) => {
      const firstName = record.get("firstName") as string;

      record.setMetadata({
        firstNameLength: firstName?.length ?? 0,
      });

      return record;
    })
  );
  ```
</CodeGroup>

## Field-level

The `metadata` object on a Field allows you to
include details like how the column of data should be transformed on egress.

### Usage

Utilize `@flatfile/api` to create or update a Workbook's fields with metadata.

```jsx
await api.workbooks.create({
  spaceId,
  name: "All Data",
  sheets: [
    {
      name: "Contacts",
      slug: "contacts",
      fields: [
        {
          key: "date_added",
          label: "Date Added",
          type: "date",
          metadata: {
            format: "MM-DD-YYYY",
          },
        },
      ],
    },
  ],
});
```

<CardGroup cols={2}>
  <Card title="typescript" icon="code-merge" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/typescript/metadata/index.ts">
    Clone the Metadata example in Typescript
  </Card>

  <Card title="javascript" icon="js" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/metadata/index.js">
    Clone the Metadata example in Javascript
  </Card>
</CardGroup>