Data Functions

The Map SDK provides a variety of data functions, allowing you to add, remove, and update datasets on your Studio Maps.

For data operations such as uploading, copying, and deleting datasets on the Studio Cloud, utilize the Data SDK.


Add Dataset

Add a local tabular or tiled dataset objects to the map. Dataset properties are passed through a dataset object. This object should contain an ID, its label text and color, and data in CSV, JSON, or GeoJSON format.

You may also specify several options, such as whether to automatically create layers from the dataset, or whether to automatically center the viewport on the newly added dataset (both options default to true).

// Assume dataset is a valid dataset

map.addDataset(
  {
    id: "test-dataset-01",
    label: "Cities",
    color: [245, 166, 35],
    data: datasetData,
  },
  {
    autoCreateLayers: true,
    centerMap: true,
  }
);
map.add_dataset(
    LocalDatasetCreationProps(
        id="sample-data",
        data=my_dataframe, # it supports str, List, DataFrame or GeoDataFrame
    ),
    auto_create_layers=False,
)

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.
Options (auto_create_layers and center_map) are passed as keyword arguments instead of an object.

ArgumentTypeDescription
datasetobjectAn object containing dataset details.
dataset.idstringUnique identifier of the dataset.
dataset.labelstringUser-facing dataset label.
dataset.colorRGBColorColor label of the dataset.
dataset.fieldsField[]Schema describing the fields of the dataset.
dataset.datastring, object, unknown[][]Data used to create a dataset, in CSV, JSON, GeoJSON format.
optionsobjectOptions available for dataset creation.
options.autoCreateLayersboolWhether or not to automatically create layers from the new dataset. Default: true
options.centerMapboolWhether or not to center the map on the dataset. Default: true

For more information, including full Python documentation, see addDataset() in the full API reference.


Add Tile Dataset

Add a tiled dataset (i.e raster or vector data) by including a reference to its remote location.

map.addTileDataset(
  {
    id: "foo",
    type: "raster-tile",
    label: "Dataset",
    color: [0, 92, 255],
    metadata: {
      // NOTE: This must be a live, reachable URL
      metadataUrl: "https://path.to.metadata.json",
    },
  },
  {
    autoCreateLayers: true,
    centerMap: true,
  }
);
map.add_tile_dataset(RasterTileDatasetRemoteCreationProps(
    id="raster-dataset-id",
    label="dataset-label",
    metadata=RasterTileRemoteMetadata(
        metadata_url="http://example.com",
    )
))

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.
Options (auto_create_layers and center_map) are passed as keyword arguments instead of an object.

ArgumentTypeDescription
dataset.idstringUnique identifier of the dataset.
dataset.labelstringUser-facing dataset label.
dataset.colorRGBColorA three-digit array representing an RGB color value.
dataset.fieldsField[]Schema describing the fields of the dataset.
dataset.metadataobjectTileset metadata.
dataset.metadata.metadataUrlstringA reachable URL path to tile metadata.
optionsobjectOptions available for dataset creation.
options.autoCreateLayersboolWhether or not to automatically create layers from the new dataset. Default: true
options.centerMapboolWhether or not to center the map on the dataset. Default: true

For more information, including full Python documentation, see addTileDataset() in the full API reference.


Get Dataset by ID

Retrieve a dataset by passing its id. If the id is associated with an existing dataset, the dataset object is returned.

This function returns the Dataset object associated with the identifier, which includes the dataset's metadata, and does not include the tabular data associated with the dataset. For this functionality, check out getDatasetWithData.

dataset = map.getDatasetById("test-dataset-01");
dataset = map.get_dataset_by_id("test-dataset-01")

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
datasetIdstringThe identifier for the dataset to retrieve.

For more information, including full Python documentation, see getDatasetById() in the full API reference.


Get Dataset with Data

Retrieve a dataset record along with its data by passing the dataset's id. This is useful if you need to retrieve or operate on data from Studio.

dataset = map.getDatasetWithData("test-dataset-01");
dataset = map.get_dataset_with_data('test-dataset-01')

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
datasetIdstringThe identifier for the dataset to retrieve.

For more information, including full Python documentation, see getDatasetWithData() in the full API reference.


Get Datasets

Note: Python Arguments require Python syntax and snake_case parameter names.

Retrieve a list of all datasets available on the map. This is returned as an array of Dataset objects, each containing the dataset's id, label, color and other specified options.

datasets = map.getDatasets();
datasets = map.get_datasets()

For more information, including full Python documentation, see getDatasets() in the full API reference.


Remove Dataset

Remove a dataset from the map by passing its id.

Important note: When a dataset is removed, all associated layers are also removed. Please ensure no layers you wish to keep rely on the dataset you wish to delete.

map.removeDataset("test-dataset-01");
map.remove_dataset('test-dataset-01')

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
datasetIdstringThe identifier of the dataset to remove.

For more information, including full Python documentation, see removeDataset() in the full API reference.


Replace Dataset

Select a dataset to replace as thisDatasetId, then provide a new Dataset object in withDataset. This function is particularly useful for replacing an existing dataset for a new one with a similar schema, updating all layers with the new data.

// suppose newDataset is a valid Dataset object
map.replaceDataset("old-dataset-01", newDataset, { strict: true });
map.replace_dataset(
    this_dataset_id="dataset-id-to-replace",
    with_dataset=LocalDatasetCreationProps(
        data=my_other_dataframe_data,
    ),
    strict=True
)

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
thisDatasetIdstringIdentifier of the dataset to replace.
withDatasetobjectA dataset object to use as a replacement.
withDataset.labelstringUser-facing dataset label.
withDataset.colorRGBColorA three-digit array representing an RGB color value.
withDataset.fieldsField[]Schema describing the fields of the dataset.
withDataset.datastring, object, unknown[][]Data used to create a dataset, in CSV, JSON, GeoJSON format.
optionsobjectOptions available for dataset replacement.
options.forceboolWhether to force a dataset replace, even if the compatibility check fails. Default: false.
options.strictboolWhether to ensure strict equality of types for each field being replaced. Default: false.

For more information, including full Python documentation, see replaceDataset() in the full API reference.


Update Dataset

Update an existing dataset's configuration by passing its id. This function should be used to update the dataset's user-facing label, color, or field schema.

map.updateDataset("test-dataset-01", {
  label: "Dataset",
  color: [245, 166, 35],
});
map.update_dataset('dataset-id', DatasetUpdateProps(
    label="My new label",
    color=(255,0,0)
))

Arguments

Note: Python Arguments require Python syntax and snake_case parameter names.

ArgumentTypeDescription
datasetIdstringThe identifier of the dataset to update.
valuesobjectThe values to update.
values.labelstringUser-facing dataset label.
values.colorRGBColorA three-digit array representing an RGB color value.
values.fieldsField[]Schema describing the fields of the dataset.

For more information, including full Python documentation, see updateDataset() in the full API reference.