DataHub Search CLI - Agent Context

Best practices for AI agents consuming datahub search.

Output Discipline

• Always use --format json (the default) for machine consumption.
• Always set --limit explicitly; default is 10, max is 50.
• Use --urns-only when piping URNs to other commands.

datahub search "customers" --format json --limit 20
datahub search "customers" --urns-only | xargs -I{} datahub get --urn {}

Projection

Use --projection to limit returned fields and reduce token cost.

# Minimal: just URNs and types
datahub search "customers" --projection "urn type"

# With dataset properties
datahub search "customers" --projection "urn type ... on Dataset { properties { name description } platform { ...PlatformFields } }"

# From a file
datahub search "customers" --projection @fields.gql

Common projections:

Use case	Projection
URN list	urn
Name + platform	urn type ... on Dataset { properties { name } platform { name } }
Schema exploration	urn ... on Dataset { schemaMetadata { fields { fieldPath type } } }

Dry Run

Always --dry-run first to verify the compiled query before executing.

datahub search "customers" --filter platform=snowflake --dry-run

The output is JSON with operation_name, graphql_field, variables, and optionally query (when --projection is set).

Filters

Use --filter key=value for simple cases (repeatable, comma for OR on same field). Use --where 'SQL expr' for SQL-like expressions (recommended for agents — most readable). Use --filters '{json}' for complex AND/OR/NOT logic.

These three options are mutually exclusive — use one at a time.

# Simple
datahub search "*" --filter platform=snowflake --filter env=PROD

# OR on same field
datahub search "*" --filter platform=snowflake,bigquery

# SQL-like WHERE (recommended for agents)
datahub search "*" --where "platform = snowflake AND env = PROD"
datahub search "*" --where "platform IN (snowflake, bigquery)"
datahub search "*" --where "entity_type = dataset AND (platform = snowflake OR platform = bigquery)"
datahub search "*" --where "glossary_term IS NOT NULL"
datahub search "*" --where "NOT env = DEV"

# Complex JSON
datahub search "*" --filters '{"and": [{"platform": ["snowflake"]}, {"env": ["PROD"]}]}'

Discover available filters:

datahub search list-filters
datahub search describe-filter platform

Pagination

Use --limit + --offset. Max 50 results per page.

datahub search "customers" --limit 50 --offset 0    # page 1
datahub search "customers" --limit 50 --offset 50   # page 2

Sorting

datahub search "*" --sort-by name --sort-order asc

Semantic Search

Beta feature. Check availability first:

datahub search diagnose --format json

Then use:

datahub search --semantic "financial reports about quarterly revenue"

Views

Apply a saved DataHub view:

datahub search "*" --view urn:li:dataHubView:my_view

Error Handling

Errors are written to stderr as JSON (in non-TTY/agent context):

{
  "error": "semantic_search_unavailable",
  "message": "...",
  "suggestion": "datahub search diagnose"
}

Error types: usage_error, search_error, semantic_search_unavailable, permission_denied, connection_error.

Exit codes: 0 success, 1 general error, 2 usage error, 4 permission denied, 5 connection error.

Common Recipes

# Find all Snowflake datasets in PROD
datahub search "*" --where "platform = snowflake AND env = PROD AND entity_type = dataset" --limit 50

# Find datasets tagged with a specific term
datahub search "*" --where "glossary_term IS NOT NULL AND platform = snowflake"

# Find entities with a tag (exact URN required)
datahub search "*" --where "tag = urn:li:tag:PII"

# Get URNs for pipeline input
datahub search "customers" --filter platform=snowflake --urns-only

# Explore available platforms and counts
datahub search "*" --facets-only --format json

# Verify query before running
datahub search "revenue" --where "platform = bigquery" --dry-run