surendranb / filter-structures

Name: surendranb/filter-structures
Author: surendranb

The correct shape for `dimension_filter` in `get_ga4_data`. Wrong structure returns an "Invalid dimension_filter" error. Use these templates.

Version

SKILL.md

3.3 KB

⚠This file contains 1 character(s) that do not render as themselves (U+FE0F). They are shown highlighted below.

Filter Structures

The correct shape for dimension_filter in get_ga4_data.
Wrong structure returns an "Invalid dimension_filter" error. Use these templates.

The one rule

Every leaf filter must be wrapped in a "filter" key. fieldName never appears at the top level.

// WRONG — fieldName at top level
{"fieldName": "sessionSource", "stringFilter": {"value": "google"}}

// CORRECT — wrapped in "filter"
{"filter": {"fieldName": "sessionSource", "stringFilter": {"value": "google"}}}

Template: single field filter

{
  "filter": {
    "fieldName": "DIMENSION_NAME",
    "stringFilter": {
      "value": "VALUE",
      "matchType": "EXACT"
    }
  }
}

matchType options: EXACT, BEGINS_WITH, ENDS_WITH, CONTAINS, FULL_REGEXP, PARTIAL_REGEXP

Template: AND — all conditions must match

{
  "andGroup": {
    "expressions": [
      {"filter": {"fieldName": "deviceCategory", "stringFilter": {"value": "mobile", "matchType": "EXACT"}}},
      {"filter": {"fieldName": "country", "stringFilter": {"value": "United States", "matchType": "EXACT"}}}
    ]
  }
}

Template: OR — any condition matches

{
  "orGroup": {
    "expressions": [
      {"filter": {"fieldName": "sessionDefaultChannelGroup", "stringFilter": {"value": "Organic Search", "matchType": "EXACT"}}},
      {"filter": {"fieldName": "sessionDefaultChannelGroup", "stringFilter": {"value": "Organic Social", "matchType": "EXACT"}}}
    ]
  }
}

Template: NOT — exclude matching sessions

{
  "notExpression": {
    "filter": {
      "fieldName": "sessionDefaultChannelGroup",
      "stringFilter": {"value": "Direct", "matchType": "EXACT"}
    }
  }
}

Template: IN LIST — match any of several values

{
  "filter": {
    "fieldName": "country",
    "inListFilter": {
      "values": ["United States", "United Kingdom", "Canada"]
    }
  }
}

Common wrong keys → correct keys

Wrong key	Correct key
`and_filter`	`andGroup`
`or_filter`	`orGroup`
`not_filter`	`notExpression`
`filters`	`expressions`
`field`	`fieldName`
`stringFilter.exact`	`stringFilter.value`

Field names are always camelCase

⚠‹VARIATION SELECTOR U+FE0F› CRITICAL FILTER TRAP: Field names in dimension_filter (inside fieldName) MUST be exact camelCase. Passing page_path or session_default_channel_group will fail with an Unknown field for FilterExpression error.

Wrong (snake_case)	Correct (camelCase)
`page_path`	`pagePath`
`session_default_channel_group`	`sessionDefaultChannelGroup`
`session_source`	`sessionSource`
`session_source_medium`	`sessionSourceMedium`
`session_campaign_name`	`sessionCampaignName`
`landing_page`	`landingPage`
`device_category`	`deviceCategory`
`event_name`	`eventName`

If you use snakecase in fieldName, the filter will fail with an "Unknown field" error. Do NOT retry snakecase.

Note

Only dimensions can be filtered with dimension_filter. To filter on metric
values (e.g. sessions > 100), you must do this in post-processing — the GA4
Data API does not support metric filters in RunReport.