## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.m3ter.com/llms.txt)

Use this file to discover all available pages before exploring further.

This topic explains how to add string or number values for a Lookup Table Revision data schema and publish and manage Table Revisions. A Revision’s data values only become available for calculations that reference the Lookup Table when the Revision is _published_:

- Data can only be added to a _draft_ Revision.
- _Only one_ Revision can be the published Revision for a Lookup Table at any given time.
- You _cannot change_ the data values of a published Revision.
- If you want to use updated data values for the Lookup Table, you must:
  - Create a new draft Revision with the same data schema, add updated values you want to use for the Table, and publish the new Revision.
  - Alternatively, you can _duplicate_ the published Revision as a new draft Revision, add updated values you want to use for the Table, and publish the new Revision.
  - When you publish a new Revision:
    - The current published Revision is _automatically archived_
    - Any Lookup functions in your calculations will now use the data values defined for the new published Revision.

In this way, you can manage and deploy Lookup Table Revisions for use cases where you need to quickly and dynamically update the data values used for your calculations. This topic continues the variable discount rate example introduced in the [previous topic](https://docs.m3ter.com/guides/lookup-tables/creating-and-managing-lookup-tables) and goes on to explain how to add data to, publish, and manage Lookup Table Revisions:

- [Adding and Managing Data for Table Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#adding-and-managing-data-for-table-revisions)
- [Publishing Table Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#publishing-table-revisions)
- [Duplicating Table Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#duplicating-table-revisions)
- [Archiving Published Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#archiving-published-revisions)
- [Copying Table Revision Data](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#copying-table-revision-data)
- [Viewing and Comparing Table Revision JSON](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#viewing-and-comparing-table-revision-json)
- [Downloading Table Revision Data](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#downloading-table-revision-data)
- [Uploading Table Revision Data](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#uploading-table-revision-data)
- [Managing Table Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#managing-table-revisions)
- [Reviewing and Managing Revision Data Jobs](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#reviewing-and-managing-revision-data-jobs)
- [Using Multiple Key Fields - Checking Revision Schema Field Order](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#using-multiple-key-fields-checking-revision-schema-field-order)

## Adding and Managing Data for Table Revisions

You can quickly add string and number values to draft Table Revisions. **To add data to a Table Revision:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Under **Revisions**, select the **Name** hotlink text of the draft Revision you want to add data to. The **Revision details** page opens.
4. Under **Revision data**, select **Create**. The **Create** page opens.
5. On **Revision data details**, enter the required string and number data values for the Revision field schema:

- For the current variable discount rate example, we’ve entered two sets of **rate** and **country** data field values for the Revision schema we set up in the [previous topic](https://docs.m3ter.com/guides/lookup-tables/creating-and-managing-lookup-tables).

6. Select **Create revision data**. You are returned to the **Revision details** page and under **Revision data** the added data values are shown for the Revision fields:

- We now have a Table Revision with the data values we want to use for our current discounted rate example added. To make these values available for any Lookup functions used in calculations, we must first _publish_ the Revision - see the [following section](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#publishing-table-revisions).

7. If you want to update the data you’ve added to the Revision before you publish it, under **Revision data** you can:

- Select **Edit** to edit the **Revision data details** for all data fields.
- Select the **Edit** button for a single data item to update it:

8. If you want to delete _all the data_ you’ve added to the Revision:

- Under **Revision data** select **Delete**. A confirmation dialog appears.
- Select to **Delete** all the Revision’s data.

9. If you want to delete a single data item:

- Select the delete icon for the data item:

- A confirmation dialog appears.

10. Select to **Delete** the single data item.

**Important: Adding data prevents updates to the Revision data field schema!** If you add data values to a Revision, you will no longer be able to edit the Revision’s data field schema to add additional fields, delete fields, change field order, or change keyed fields. See the following [Managing Table Revisions](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#managing-table-revisions) section.

## Publishing Table Revisions

When you’ve added any required data values to a draft Table Revision, you can publish it and make the values available to any Lookup functions used in calculations that reference the Lookup Table. **To publish a Table Revision:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. On the **Revisions** panel under **Actions**, select the **Publish** icon for the **DRAFT** Revision you want to publish:

- The **Revisions** panel adjusts and shows the Revision’s **Status** as **PUBLISHED**:

4. Alternatively, select the **Name** hotlink text of the Revision you intend to publish. The **Revision details** page opens:

- On the **Revision data** panel you can review and check the values of the data fields for the draft Revision before you go ahead and publish it.

5. On the **Revision details** panel, select **Publish**:

- A confirmation dialog appears and reminds you that this action will archive the currently published version.

6. Select **Publish** to confirm. The **Revision details** panel adjusts and shows the Revision as **PUBLISHED**:

Note that:

- You cannot update or delete a **PUBLISHED** Table Revision.
- Any Lookup functions used in calculations that reference the Lookup Table will now use the data values on the newly published Revision.
  - If you subsequently want to update a Revision to ensure different data values are used by Lookup functions, you must create a new draft Table Revision, populate it with the required data values, and _publish_ the new Revision.
  - If you want to use the same data schema for the new Revision, you can simply duplicate the **PUBLISHED** Revision in draft status, update the data values, and then publish the duplicate to supersede the currently published Revision - see the [following section](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#duplicating-table-revisions).

We now have a published Revision of the **Discount Vol Rates** Lookup Table. This will make available to Lookup functions the data values we want to use for our current discounted usage rate example:

- The following [Worked Example](https://m3ter.mintlify.app/guides/lookup-tables/worked-example-variable-usage-discounting) topic explains how to set up a derived field on a Meter with a calculation that uses a Lookup function referencing the **Discount Vol Rates** Lookup Table. This function will apply the discount rates by country to measured usage. The example goes on to show how to check that Accounts in different countries are billed according to the appropriate discounted usage measures.

## Duplicating Table Revisions

In many cases of using Lookup Tables to fulfill dynamic data mapping use cases, you’ll want to use the same data schema as the currently published Table Revision. You can quickly duplicate the currently published Table Revision as a draft, add new data values as required, and then publish the updated draft Revision. **To duplicate a Table Revision:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Revision you want to duplicate. The **Revision details** page opens.
4. On the **Revision details** panel, select **Duplicate**:

A confirmation dialog opens:

5. Select **Duplicate** to confirm. The Table Revision is duplicated and if you open the **Lookup Table details** page, the duplicate is now listed on the **Revisions** panel:

The new duplicate Revision:

- Uses the original Revision’s name with “Copy” appended.
- Inherits the original Revision’s data schema and any data values.
- Is created as a **DRAFT** Revision.

6. You can now edit the duplicate Revision, as required.

## Archiving Published Revisions

If you have published a Table Revision, created a new draft Revision, and then publish the draft, the existing published Revision is _archived automatically_. You can also _manually archive_ the Published Revision.

**Warning!** If you’ve referenced the Lookup Table in a calculation and you archive the published Table Revision, values _will not be available_ for the calculation until you publish another Revision.

**To archive the published Table Revision:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. On the **Revisions** panel under **Actions**, select the **Archive** button for the **PUBLISHED** Revision:

A confirmation dialog appears:

4. Select **Archive**. The **Status** of the Table Revision now shows as **ARCHIVED** on the **Revisions** panel:

## Copying Table Revision Data

You can copy a Table Revision’s data to another Revision:

- Copy the data from the current Revision to a destination Revision.
- Copy the data from a source Revision to the current Revision.

**Notes and Warnings:**

- **Check source and destination Revision data schema match!** If you attempt to copy data from one Revision to another and their data schema do not match, the copy will fail and you’ll receive an error.
- **Restrictions when copying Revision data**. Some restrictions are imposed when copying Revision data - you cannot:
  - Copy data to a **PUBLISHED** Revision.
  - Copy data to or from an **ARCHIVED** Revision.
  - Copy data from a Revision that is empty and has no data values added.

**To copy Table Revision data:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Table Revision you want to copy data from or copy data to. The **Revision details** page opens.
4. On the **Revision data** panel, select **Copy**. A drop-down menu appears with two options.

5. If you want to copy data from the current Revision to another Revision, select **Copy data to destination revision**. A **Select revision** dialog appears:

Note that in this example:

- The current Revision is **Discount Vol Rates Rev 4** and cannot be selected as the destination Revision.
- Any **ARCHIVED** or the **PUBLISHED** Revision cannot be selected as a destination Revision.

6. Select the Table Revision you want to _copy data to_ and select **Confirm**. A copy job is run:

- If the copy job completes successfully, a message shows to confirm.
- If the copy job fails, you’ll receive an error.
  - A common cause of copy data error is when the source and destination Revision data schema do not match.
  - You can select **Revision data jobs** to review and check copy data jobs. See below [Reviewing and Managing Revision Data Jobs](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#reviewing-and-managing-revision-data-jobs).

7. If you want to copy the data from another Revision to the current Revision, then select **Copy data from source revision**. A **Select revision** dialog appears:

Note that in this example:

- The current Revision is **Discount Vol Rates Rev 4** and cannot be selected as the source Revision.
- Any **ARCHIVED** Revisions or empty Revisions - such as **Discount Vol Rates Rev 5** in this example - cannot be selected as the source Revision.

8. Select the Table Revision you want to _copy data from_ and select **Confirm**. A copy job is run:

## Viewing and Comparing Table Revision JSON

As an aid to managing Table Revisions, you can view the JSON for a Revision and open and compare it with another Table Revision’s JSON. **To view Table Revision JSON:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Table Revision you want to view JSON for. The **Revision details** page opens.
4. On the **Revision details** panel, select **View JSON**. A modal opens allowing you to review the Revision’s JSON:

- You can **Copy** the JSON to your clipboard.

5. If you want to compare the Table Revision’s JSON with that of another Revision, use the **Select revision to compare** drop-down to select the other Revision. The modal adjusts to add in the selected Revision as **Comparator** to the **Original**:

- Differences in the JSON are highlighted.

6. Select **Close** to end your view Revision JSON session.

## Downloading Table Revision Data

You can download a Lookup Table Revision’s data in either JSONL or CSV format. **To download a Table Revision’s data:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Revision whose data you want to download. The **Revision details** page opens.
4. On the **Revision data** panel, select **Download data**. A popup menu appears.
5. Select the format which you want to use for the download - **Download JSONL** or **Download CSV**:

- The revision data is compiled in the selected format and a file downloaded locally.
- You can then open the downloaded file using your preferred application and review the Revision’s data.

**Tip: Downloading ARCHIVED Revision data?** If you open Revision details for an **ARCHIVED** Revision, then the **Revision data** panel will show **no revision data**. This is because when a Revision is archived, its data is stored remotely. However, when you download an **ARCHIVED** Revision, its data values are retrieved from remote storage and included in the downloaded file.

## Uploading Table Revision Data

Instead of manually adding Revision data, as explained in the [previous section](https://docs.m3ter.com/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#adding-and-managing-data-for-table-revisions), you can upload either a JSONL or CSV formatted file to either create the initial Revision schema data values or to update the existing data values.

**Note:** You can only upload data to a **DRAFT** Revision.

**To upload Table Revision data:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Revision you want to upload data values for. The **Revision details** page opens and the **Revision data** panel shows the existing data values for the Revision schema fields:

4. On the **Revision data** panel, select **Upload revision data**:

The panel adjusts to allow you to either drag and drop a file or use **Select files** to open a **File upload** dialog to select a file for upload:

- When you drag & drop or select a JSONL or CSV formatted file, the data values contained in the file are uploaded and used to either create new data values for the Revision schema fields or to overwrite existing values.
- At upload, a validation check is performed against selected files. If a file is not correctly JSONL or CSV formatted or contains data fields that don’t match the Revision’s schema, then the upload is blocked and you’ll receive an error.

You’ll receive a confirmation when the upload job has succeeded:

5. Select **Revision data**. You can then check that the values contained in the uploaded file have either created new data values or updated the existing values:

## Managing Table Revisions

You can edit or delete a draft Table Revision at any time. However:
- You _cannot edit_ a published or archived Table Revision.
- You _cannot delete_ a published Table Revision.

**To manage Lookup Table Revisions:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. If you want to edit a Table Revision, on the **Revisions** panel select the **Edit** icon:

- Alternatively, select the **Name** hotlink text for the Revision to open the **Revision details** page and then select **Edit**.

The **Edit** page opens.

4. Make your editing changes and select **Update** revision.

**Important: Data already added to a Revision!** If you’ve already added data values to a Revision, when you open the **Edit** page, you _will not be able to make any changes_ to the Revision’s data field schema. You must first delete any data values, re-open the **Edit** page to make any required changes to the Revision’s data field schema, and then add in new data values.

5. If you want to delete a Table Revision, on the **Revisions** panel select the **Delete** icon:

A confirmation dialog appears.

6. Select **Delete** to confirm the delete action.

## Reviewing and Managing Revision Data Jobs

On the **Revision details** page, you can review and manage data jobs that have run for a Revision’s data. There are four types of Lookup Table Revision data jobs:

- **ARCHIVE**. Job runs for the existing **PUBLISHED** Revision and you publish a **DRAFT** Revision, which means the existing Revision is automatically archived.
- **DOWNLOAD**. Job runs when you download a Revision’s data.
- **UPLOAD**. Job runs when you upload a data file to create or update a Revision’s data values.
- **COPY**. Job runs when you duplicate a Revision or copy a Revision’s data to another Revision.

You can quickly check the status of a Revision’s data jobs and manage them. If a data job has failed, then a failure reason is given allowing you to follow-up and troubleshoot.

**To review and manage Table Revision data jobs:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. Select the **Name** hotlink text of the Revision you want to review and manage the data jobs for. The **Revision details** page opens.
4. On the **Revision data** panel, select **Review data jobs**:

The **Status** of a Revision data job can be one of three states:
- **PENDING**. The job is queued and has not yet run.
- **SUCCEEDED**. The job ran successfully.
- **FAILED**. The job ran unsuccessfully and you can read-off the **Failure reason**.

5. If you want to delete a Revision data job, under **Actions** select the delete icon:

A confirmation dialog appears.

6. Select **Delete**.

## Using Multiple Key Fields - Checking Revision Schema Field Order

Your use case when utilizing a Lookup Table might require multiple key fields to be defined for the Lookup Table Revision schema. For example, suppose you want a variable cost amount to be applied which is determined on the basis of three key field values for country, region and charge type. To meet the case you plan to use a `Lookup.findNumber()` function, such as:

> `Lookup.findNumber("cost_lookup", "cost", 1, "country", "region", "type")`

For this type of case, you must ensure the order in which you’ve set up the three key fields for the published Lookup Table Revision schema _corresponds to_ the order you have used the key fields in the Lookup function. For the above function, the Revision schema key field order would need to be:

Notes:
- The top-to-bottom order of the key fields must match the left-to-right order of the key field parameter used in your Lookup function, since this is the order they will be passed into the function.
- The names used for the fields in the Revision schema don’t have to match the names used in the Lookup function.
- Non-key field order doesn’t need to match.

### Reordering Revision Schema Key Fields

After setting up a Table Revision schema, you might need to edit it and reorder the key fields to ensure the order matches the order you’ve used in a Lookup function.

**To reorder Revision schema key fields:**

1. Select **Settings>Lookup tables**. The **Lookup tables** page opens.
2. Select the **Name** hotlink text of the Lookup Table. The **Lookup table details** page opens.
3. On the Revisions panel, select the **Name** hotlink text of the Revision. The **Revision details** page opens.
4. Select **Edit**.
5. On the **Revision fields** card, select **Revision fields order**. A drop-down **Order** menu appears.

- Note that if you’ve already added data values for the Revision schema fields, you won’t be able to edit the field order. You’ll first have to delete any Revision data.

6. On the **Order** menu select the field you want to move and drag and drop to where you want to place it in the field order:

7. When you have achieved the required key field order, select **Update revision**.