> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-docs-update-8de3b114-e6aa-4417-a753-2ecef733a0d.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](/documentation/sdks/react/components#space).

## 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>