Troubleshooting GraphQL Container Filtering Issues – DataHub Customer Support Portal

Area: API Issues

Sub-Area: GraphQL Search and Filtering

Issue

When filtering datasets by container URNs in GraphQL queries, users encounter two common issues: filtering by Level 2+ container URNs (such as Snowflake database containers) returns no results even when datasets exist under those containers, and attempting to filter by container names instead of URNs fails to return expected results. These issues stem from how DataHub's GraphQL API handles container hierarchy traversal and filter field requirements.

You Might Be Asking

Why doesn't filtering by a database-level container URN return datasets from child schemas?
Can I filter datasets by container name instead of the full URN?
Why do Level 1 container filters work but Level 2+ filters don't?
How can I search for datasets across an entire container hierarchy?

Solution

For Level 2+ Container Hierarchy Filtering

Use the DESCENDANTS_INCL condition to enable container expansion that walks the hierarchy and includes all nested children:

query {
  searchAcrossEntities(
    input: {
      types: [DATASET],
      query: "*",
      orFilters: [{
        and: [{
          field: "container",
          values: ["urn:li:container:<your-database-container-urn>"],
          condition: DESCENDANTS_INCL
        }]
      }]
    }
  ) {
    start
    count
    total
    searchResults {
      entity {
        urn
        type
      }
    }
  }
}

The default EQUAL condition only matches datasets whose immediate parent container matches the provided URN. Level 1 containers (like schemas) work because datasets store the schema URN directly. Level 2 containers (like databases) fail because datasets don't store the database URN - they only store their immediate parent schema URN.

For Container Name-Based Filtering

Container filters require full URNs, not human-readable names. Use a two-step approach:

First, resolve the container name to its URN:

query {
  searchAcrossEntities(
    input: {
      types: [CONTAINER],
      query: "YOUR_CONTAINER_NAME"
    }
  ) {
    searchResults {
      entity {
        urn
        ... on Container {
          properties {
            name
          }
        }
      }
    }
  }
}

Then use the returned URN in your dataset filter:

query {
  searchAcrossEntities(
    input: {
      types: [DATASET],
      query: "*",
      orFilters: [{
        and: [{
          field: "container",
          values: ["<urn-from-step-1>"],
          condition: DESCENDANTS_INCL
        }]
      }]
    }
  ) {
    searchResults {
      entity {
        urn
        type
      }
    }
  }
}

Additional Notes

All filter fields in DataHub's GraphQL API are URN-based by design - this applies to containers, datasets, and other entity types. The DESCENDANTS_INCL condition leverages DataHub's ContainerExpansionRewriter which uses IsPartOf relationships in the graph to traverse the container hierarchy. The expansion logic requires the SEARCH_SERVICE_FILTER_CONTAINER_EXPANSION_ENABLED environment variable to be true (which is the default). Container name-based filtering is not supported natively and would require a feature enhancement.