# Metadata

> Learn how to access, modify, and use metadata in scenes to identify and process occurrences.

[API reference](/asset-transformer-sdk/2026.4/api/python/scene_types.md#metadata)

Metadata are components that store basic key-value information that is retrieved from imported files. Use the API to read, add, modify, and delete metadata.

To access this information, use these functions:

* [core.listProperties](/asset-transformer-sdk/2026.4/api/python/core_functions.md#listproperties)
* [core.getProperty](/asset-transformer-sdk/2026.4/api/python/core_functions.md#getproperty)

To directly extract this information, use this function:

* [scene.getMetadatasDefinitions](/asset-transformer-sdk/2026.4/api/python/scene_functions.md#getmetadatasdefinitions)

To retrieve occurrences that match specific metadata, use this function:

* [scene.findOccurrencesByMetadata](/asset-transformer-sdk/2026.4/api/python/scene_functions.md#findoccurrencesbymetadata)

> **Note:**
>
> Metadata can be very usefull to identify occurrences and apply a specific process on them. But they contribute to increase the final size of your 3D file.

## Code example

### Create new occurrences with metadata attached

Let's create a test scene with multiples occurrences and try to attach metadata on them.

```python title="Python"
def createTestScene():
    root = scene.getRoot()

    occurrence1 = scene.createOccurrence(name="occ1", parent=root)
    # Add a metadata component to the occurrence
    metadata_comp1 = scene.addComponent(occurrence1, scene.ComponentType.Metadata)
    # Add some values to this metadata
    scene.addMetadata(metadata_comp1, "m_1", "myValue1")
    scene.addMetadata(metadata_comp1, "m_2", "myValue2")

    occurrence2 = scene.createOccurrence(name="occ2", parent=occurrence1)
    metadata_comp2 = scene.addComponent(occurrence2, scene.ComponentType.Metadata)
    # More efficient way to populate metadata with multiple values
    scene.addMetadataBlock(metadata_comp2, ["m_2", "m_3", "m_4"], ["myValue3", "myValue4", "myValue5"])

    occurrence3 = scene.createOccurrence(name="occ3", parent=occurrence1)
    metadata_comp3 = scene.addComponent(occurrence3, scene.ComponentType.Metadata)
    scene.addMetadata(metadata_comp3, "m_3", "myValue6")

    occurrence4 = scene.createOccurrence(name="occ4", parent=root)

```

### Print the hierarchy tree and the metadata attached

We want to be able to print the name of each occurrence and their associated metadata.

```python title="Python"
# Go through the product structure using "depth first" recursive method and retrieve and display metadata
def dfPrintOccurrencesNameAndMetadata(offset, occurrence):

    occurrence_info = scene.getOccurrenceName(occurrence)
    # Ensure occurrence has a metadata attached before trying to access it
    if scene.hasComponent(occurrence, scene.ComponentType.Metadata):
        occurrence_info = occurrence_info + ", metadata: "
        metadata_comp = scene.getComponent(occurrence, scene.ComponentType.Metadata)
        metadata_definitions = scene.getMetadatasDefinitions([metadata_comp])[0]
        for metadata in metadata_definitions:
            metadata_info = f'(name: {metadata.name}, value: {metadata.value})'
            occurrence_info = occurrence_info + metadata_info

    print(offset + occurrence_info)
    offset = offset + " |- "
    for child in scene.getChildren(occurrence):
        dfPrintOccurrencesNameAndMetadata(offset, child)

```

### Output

Root
\|- occ1, metadata: (name: m\_1, value: myValue1)(name: m\_2, value: myValue2)
\|-  |- occ2, metadata: (name: m\_2, value: myValue3)(name: m\_3, value: myValue4)(name: m\_4, value: myValue5)
\|-  |- occ3, metadata: (name: m\_3, value: myValue6)
\|- occ4

### Filter the metadata in the scene

To cleanup our scene, and remove useless information, we want to filter all the metadata with specific names contained in a blacklist.

```python title="Python"

def removeBlacklistedMetadata():
    # Retrieve all the occurrences in the scene
    occurrences = scene.findOccurrencesByProperty("Name", ".*")
    # Retrieve all the associated metadata components
    metadata_components = scene.getComponentByOccurrence(occurrences, pxz.scene.ComponentType.Metadata, True)

    black_listed_metadata_names = ['m_2', 'm_3']
    # Change to a set structure to perform faster search
    black_listed_metadata_set = set(black_listed_metadata_names)

    metadata_definitions = scene.getMetadatasDefinitions(metadata_components)
    for i in range(len(metadata_definitions)):
        for metadata in metadata_definitions[i]:
            if metadata.name in black_listed_metadata_set:
                scene.removeMetadata(metadata_components[i], metadata.name)

```

#### Output

```py
Root
|- occ1, metadata: (name: m_1, value: myValue1)
|-  |- occ2, metadata: (name: m_4, value: myValue5)
|-  |- occ3, metadata: 
|- occ4
```

### Identify an occurrence by metadata

Let's assume we want to rename every occurrence that contain a specific metadata.

```python title="Python"
def selectOccurrencesByMetadataAndRenameThem():
    # We retrieve all the occurrence with a metadata containing a value "myValue1"
    occurrences_found_by_value = scene.findOccurrencesByMetadataValue("myValue1")

    for occurrence in occurrences_found_by_value:
        name = scene.getOccurrenceName(occurrence)
        scene.setOccurrenceName(occurrence, name + " retrieved by value")

    # We retrieve all the occurrence with a metadata named "m_1" no matter the value associated with
    occurrences_found_by_value = scene.findOccurrencesByMetadata("m_4", ".*")
    for occurrence in occurrences_found_by_value:
        # Another way to get occurrence name
        name = core.getProperty(occurrence, "Name")
        # Another way to set occurrence name. A name is a property of the occurrence
        core.setProperty(occurrence, "Name", name + " retrieved by name")

```

#### Output

```py
Root
|- occ1 retrieved by value, metadata: (name: m_1, value: myValue1)
|-  |- occ2 retrieved by name, metadata: (name: m_4, value: myValue5)
|-  |- occ3, metadata: 
|- occ4
```