> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m3ter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Adding Data to, Publishing, and Managing Lookup Table Revisions
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](/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](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#adding-and-managing-data-for-table-revisions)
* [Publishing Table Revisions](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#publishing-table-revisions)
* [Duplicating Table Revisions](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#duplicating-table-revisions)
* [Archiving Published Revisions](#archiving-published-revisions)
* [Copying Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#copying-table-revision-data)
* [Viewing and Comparing Table Revision JSON](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#viewing-and-comparing-table-revision-json)
* [Downloading Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#downloading-table-revision-data)
* [Uploading Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#uploading-table-revision-data)
* [Managing Table Revisions](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#managing-table-revisions)
* [Reviewing and Managing Revision Data Jobs](/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](/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](/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](/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](/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](/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 the 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 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](/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:
* 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](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#reviewing-and-managing-revision-data-jobs).
## 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](/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. See above [Publishing Table Revisions](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#publishing-table-revisions).
* **DOWNLOAD**. Job runs when you download a Revision's data. See above [Downloading Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#downloading-table-revision-data).
* **UPLOAD**. Job runs when you upload a data file to create or update a Revision's data values. See above [Uploading Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#uploading-table-revision-data).
* **COPY**. Job runs when you:
* Duplicate a Revision. See above [Duplicating Table Revisions](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#duplicating-table-revisions).
* Copy a Revision's data to another Revision. See above [Copying Table Revision Data](/guides/lookup-tables/adding-data-to-and-publishing-table-revisions#copying-table-revision-data).
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 doesn'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**.