# Metadata management
<subtitle>Attach custom key-value pairs to the sandbox, making it easy to associate sessions, mark tasks, and filter by conditions. </subtitle>

Metadata is a set of custom key-value pairs attached to the sandbox. It does not change the sandbox running behavior, but it can help you identify, correlate and filter sandboxes in your business systems.

Common uses include:

- **Session Association**: Bind the sandbox to an end-user session, conversation, or task ID.
- **User Association**: Record the user ID, tenant ID or project ID on the business side.
- **Task Category**: Mark the sandbox purpose, such as `data-analysis`, `code-agent`, `preview`.
- **Batch Management**: Cooperate with `Sandbox.list()` to find a batch of sandboxes and perform cleaning, recovery or monitoring operations.

> It is not recommended to store sensitive information such as API Key, access token, password, etc. in metadata. Metadata is more suitable for storing business identifiers for retrieval and classification.

## Set metadata when creating a sandbox

When creating a sandbox, you can pass in custom key-value pairs through the `metadata` parameter.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "user_id": "user_123",
        "session_id": "session_abc",
        "task_type": "data-analysis",
    },
)

print(sandbox.sandbox_id)
```

## Read sandbox metadata

Sandbox details can be obtained through `get_info()` and the `metadata` field in it can be read.

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "user_id": "user_123",
        "task_type": "data-analysis",
    },
)

info = sandbox.get_info()
print(info.metadata)

# Output example:
# {
#     "user_id": "user_123",
#     "task_type": "data-analysis",
# }
```

## Access metadata through list interface

The sandbox information returned by `Sandbox.list()` also contains metadata. You can do further processing based on metadata in business logic.

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list()
running_sandboxes = paginator.next_items()

for sbx in running_sandboxes:
    if sbx.metadata.get("task_type") == "data-analysis":
        print("Found analysis sandbox:", sbx.sandbox_id)
```

## Filter sandbox by metadata

With `SandboxQuery`, you can directly query qualified sandboxes by metadata. For more list query methods, please refer to [List Query](/docs/agent-sandbox/sandbox/list.md).

```python
from ucloud_sandbox import Sandbox, SandboxQuery

paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "user_123",
            "task_type": "data-analysis",
        },
    ),
)

sandboxes = paginator.next_items()

for sbx in sandboxes:
    print(sbx.sandbox_id, sbx.metadata)
```

## Usage suggestions

- Use stable key naming, such as `user_id`, `session_id`, `task_type`.
- It is recommended to keep the value of metadata short to facilitate indexing and filtering.
- If you need to search the sandbox by multiple dimensions, write these dimensions into the metadata when creating it.
- Sandboxes that are no longer needed should be destroyed in time after the task is completed. Metadata is only responsible for marking and will not automatically manage the life cycle.