How to Create Dimension Mappings

This guide walks through the process of creating and registering dimension mappings. The same process applies whether you are preparing mappings for dataset submittal, a project query, or a standalone dataset query.

Prerequisites

Steps

1. Identify Source and Target Dimensions

Determine which of your dataset’s dimensions need to be mapped and what the target dimensions should be.

For dataset submittal: The project config defines the target (base) dimensions. Use the registry browser or project config repository to inspect them.

For dataset queries: You choose the target dimensions yourself — for example, mapping county-level data to state-level.

Compare each dimension type between source and target:

# List dimensions in the registry
dsgrid registry dimensions list

# Filter by type
dsgrid registry dimensions list -f "Type == geography"

2. Check If Target Dimensions Exist

Search the registry for existing dimensions that match your target:

dsgrid registry dimensions list -f "Type == geography"

If the target dimension already exists, note its dimension_id and version for use in the mapping config’s to_dimension field.

3. Register Target Dimensions (If Needed)

If the target dimension does not exist, create a dimension config and records file, then register it:

// state_dimension.json5
{
  dimensions: [
    {
      "class": "State",
      type: "geography",
      name: "US States L48",
      file: "dimensions/states.csv",
      description: "US states in the lower 48.",
    },
  ],
}

dsgrid registry dimensions register state_dimension.json5 \
    -l "Register US states dimension"

4. Choose a Mapping Type

Select the appropriate mapping_type based on the relationship between source and target records. See Dimension Mapping Types for the complete reference, including a decision tree.

Common choices:

  • many_to_one_aggregation — Reducing granularity (e.g., counties → states)

  • one_to_one — Renaming or subsetting records

  • many_to_many_explicit_multipliers — Interpolation with custom weights

5. Create a CSV Records File

Create a CSV file with the mapping records. All mapping files have from_id and to_id columns. Some mapping types also require a from_fraction column.

Note

Every from_id and to_id value must be a valid record in the corresponding registered dimension, but you do not need to list every record from those dimensions. Source records omitted from from_id are excluded from the mapping. Target records omitted from to_id are not populated by the mapping.

Example: County to state aggregation (many_to_one_aggregation)

from_id,to_id
01001,AL
01003,AL
01005,AL
06001,CA
06003,CA

Example: Interpolation (many_to_many_explicit_multipliers)

from_id,to_id,from_fraction
2018,2017,0
2018,2018,1
2018,2019,0.5
2020,2019,0.5
2020,2020,1

Tip

To drop source records that have no target equivalent, set to_id to an empty value (leave the field blank after the comma).

6. Write the Mapping Config

Create a JSON5 config file referencing the CSV records. Each from_dimension and to_dimension identifies a registered dimension by type, dimension_id, and version. Use dsgrid registry dimensions list to find the IDs.

Note

dimension_id is a UUID assigned automatically when a dimension is registered (e.g., c5e76cb6-4537-4f17-9db9-1e7eeda55eb9). It is not user-specified.

{
  mappings: [
    {
      description: "County to state aggregation",
      file: "dimension_mappings/county_to_state.csv",
      mapping_type: "many_to_one_aggregation",
      from_dimension: {
        type: "geography",
        dimension_id: "<from-dimension-uuid>",
        version: "1.0.0",
      },
      to_dimension: {
        type: "geography",
        dimension_id: "<to-dimension-uuid>",
        version: "1.0.0",
      },
    },
  ],
}

7. Register the Mapping

dsgrid registry dimension-mappings register dimension_mappings.json5 \
    -l "Register county-to-state mapping"

Note

If you are submitting a dataset to a project, mappings can be registered automatically as part of the register-and-submit-dataset command. See the Create and Submit a Dataset tutorial.

8. Verify

Confirm the mapping was registered:

# List registered mappings
dsgrid registry dimension-mappings list

# Show details
dsgrid registry dimension-mappings show <mapping-id>

# Export to inspect locally
dsgrid registry dimension-mappings dump <mapping-id> -d output_dir/

Next Steps