Working with Datasets¶

Datasets are collections of events in Honeycomb. This guide shows how to manage them.

Listing Datasets¶

async def list_datasets(client: HoneycombClient) -> list[Dataset]:
    """List all datasets in the environment.

    Args:
        client: Authenticated HoneycombClient

    Returns:
        List of datasets
    """
    datasets = await client.datasets.list_async()
    for dataset in datasets:
        print(f"{dataset.name} ({dataset.slug})")
        print(f"  Columns: {dataset.regular_columns_count}")
    return datasets

Getting a Dataset¶

async def get_dataset(client: HoneycombClient, slug: str) -> Dataset:
    """Get a specific dataset by slug.

    Args:
        client: Authenticated HoneycombClient
        slug: Dataset slug to retrieve

    Returns:
        The dataset object
    """
    dataset = await client.datasets.get_async(slug)
    print(f"Name: {dataset.name}")
    print(f"Slug: {dataset.slug}")
    print(f"Description: {dataset.description}")
    print(f"Columns: {dataset.regular_columns_count}")
    return dataset

Creating a Dataset¶

async def create_dataset(client: HoneycombClient, name: str | None = None) -> str:
    """Create a new dataset.

    Args:
        client: Authenticated HoneycombClient
        name: Optional dataset name (defaults to unique name with timestamp)

    Returns:
        The created dataset slug
    """
    # Use timestamp for unique name if not provided
    dataset_name = name or f"test-dataset-{int(time.time())}"
    dataset = await client.datasets.create_async(
        DatasetCreate(
            name=dataset_name,
            description="Created for testing",
            expand_json_depth=2,
        )
    )
    return dataset.slug

Updating a Dataset¶

async def update_dataset(client: HoneycombClient, slug: str) -> Dataset:
    """Update an existing dataset.

    Args:
        client: Authenticated HoneycombClient
        slug: Dataset slug to update

    Returns:
        The updated dataset
    """
    # Use DatasetUpdate for partial updates - only specified fields are changed
    dataset = await client.datasets.update_async(
        slug,
        DatasetUpdate(
            description="Updated description",
        ),
    )
    return dataset

Delete Protection¶

Datasets can be protected from accidental deletion. Use the set_delete_protected method or include delete_protected in an update:

async def toggle_delete_protection(client: HoneycombClient, slug: str) -> Dataset:
    """Enable or disable delete protection on a dataset.

    Args:
        client: Authenticated HoneycombClient
        slug: Dataset slug

    Returns:
        The updated dataset
    """
    # Enable delete protection to prevent accidental deletion
    dataset = await client.datasets.set_delete_protected_async(slug, protected=True)
    print(f"Delete protection enabled: {dataset.delete_protected}")

    # Or disable it when you need to delete the dataset
    dataset = await client.datasets.set_delete_protected_async(slug, protected=False)
    print(f"Delete protection disabled: {dataset.delete_protected}")

    return dataset

You can also check if a dataset is protected:

async with HoneycombClient(api_key="...") as client:
    dataset = await client.datasets.get_async("my-dataset")
    print(f"Delete protected: {dataset.delete_protected}")

Deleting a Dataset¶

Permanent Deletion

Deleting a dataset is permanent and cannot be undone!

Delete Protection

Datasets with delete protection enabled cannot be deleted. You must first disable delete protection using set_delete_protected(slug, protected=False).

async with HoneycombClient(api_key="...") as client:
    # First, disable delete protection if enabled
    await client.datasets.set_delete_protected_async("dataset-to-delete", protected=False)
    # Then delete
    await client.datasets.delete_async("dataset-to-delete")
    print("Dataset deleted")