Filter with CQL
Write a cost filter as one line of CQL, the Costfluent Query Language, including OR, which filter clauses cannot express.
CQL, the Costfluent Query Language, writes a cost filter as one line of text:
Code
It is another way to write the same filter a report's filter clauses build, and it can also combine conditions with OR. Everywhere a cost filter is accepted, CQL is accepted too: cost reports, virtual tag rules, saved filters, the Public API and the Terraform provider. Costfluent stores every filter as its JSON document and returns it in that form, saved filters and cost alerts included.
Before you start
- A workspace with at least one connected source, so there are cost values to match.
- Values are case-sensitive and must match the values a filter clause lists, except with
~*and!~*, which ignore case, spaces, hyphens and underscores. On a report, select Add filter, open the clause's values, and copy one exactly: the list shows the values with cost in the report's date range, largest first, and its search box finds one further down. - A provider is written as its key, such as
aws,azure,gcporkubernetes, the same key the Public API returns. The provider's name, such asAmazon Web Services, is a separate field,costs.provider_name.
Write a filter in a report
- Open a report under Cost reports and choose Edit as text beside Add filter, above the chart.
- The Filter as CQL box shows the current filter as CQL text, under a line saying that CQL can also combine conditions with OR. Edit it, or write a new filter.
- Choose Apply, or press Ctrl+Enter (⌘+Enter on a Mac). The report updates, and the filter is kept in the page address as an unsaved change; Save changes keeps it in the report. See Save and manage reports.
If the text does not parse, the box shows why and names the character position, such as Unknown field 'costs.colour' ending in (at position 34), and the current filter stays in place. CQL reference in the box opens this page.
A filter that uses OR has no clause form, so for such a filter the clauses step aside and the Filter as CQL box is the editor. A clause holding several patterns, written as LIKE ANY (...), shows its values read-only, because the clause's single value box would keep only the first.
Fields
| CQL | Filter field |
|---|---|
costs.provider | Provider |
costs.provider_name | Provider name |
costs.account_id | Sub-account |
costs.account_name | Sub-account name: the name the bill gives the account |
costs.service | Service |
costs.region | Region |
costs.resource_name | Resource |
costs.resource_group | Resource group: the Azure resource group, read from the resource id |
costs.charge_category | Charge category: Usage, Purchase, Tax, Credit or Adjustment |
costs.cluster | Cluster |
costs.namespace | Namespace |
costs.provider_account_id | Billing account |
costs.provider_account_name | Billing account name: the name the bill gives the account, never a connection's name a report may show beside its id |
costs.category | Service category |
costs.subcategory | Service subcategory |
costs.usage_unit | Usage unit |
costs.charge_class | Charge class: Correction for a charge that corrects an earlier period |
costs.resource_id | Resource ID |
costs.commitment_status | Commitment status: Used or Unused |
costs.commitment_type | Commitment type: SavingsPlan, ReservedInstance or CommittedUseDiscount |
costs.commitment_id | Commitment: the provider's id for it, such as a Savings Plan's ARN |
costs.pricing_category | Pricing category: Standard, Dynamic, Committed or Other, and none on a tax |
costs.sku | SKU: the provider's label for what was billed, or the SKU id of a line without one |
costs.sku_id | SKU ID: the provider's id for what was billed |
costs.operation | Operation: the AWS operation billed, such as RunInstances |
costs.charge_description | Charge description: the bill's own text for the line |
costs.resource_type | Resource type: the kind of resource billed, as the provider names it |
costs.product_family | Product family: Azure's service family, such as Compute |
costs.invoice_id | Invoice ID: the provider's invoice the line is billed on |
costs.invoice_issuer | Invoice issuer: the provider's legal entity that invoices the line, such as Amazon Web Services EMEA SARL |
costs.billing_period | Billing period: the month invoiced, written YYYY-MM, such as '2026-03' |
costs.tagged | Tagged: 'true' for a row with a tag Costfluent did not add itself, 'false' for an untagged one (Explore cost data names the keys Costfluent adds) |
costs.tag_compliance | Tag compliance: 'compliant' for a row carrying every key the workspace's tag policy requires of its provider and account, 'non_compliant' for a row missing one |
tags->>'key' | Tag, with its tag key |
virtual_tags->>'vtag_...' | Virtual tag, named by its id |
costs.segment | Segment, named by its id (seg_...): the cost your allocation rules assign to the segment, plus its share of shared cost |
Operators
| Write | Means |
|---|---|
f = 'v' | is any of v |
f != 'v' or f <> 'v' | is none of v |
f IN ('a', 'b') / f NOT IN ('a', 'b') | is any of / is none of |
f LIKE '%v%' / 'v%' / '%v' | contains / starts with / ends with |
f NOT LIKE '%v%' / 'v%' / '%v' | does not contain / does not start with / does not end with |
f LIKE 'v' / f NOT LIKE 'v' | is any of / is none of v |
f LIKE ANY ('a%', 'b%') | matches at least one pattern |
f NOT LIKE ALL ('a%', 'b%') | matches none of the patterns |
f LIKE ALL (...) / f NOT LIKE ANY (...) | one condition per pattern, joined with AND / OR |
f ~* 'v' / f !~* 'v' | flexibly matches / does not flexibly match v: equal once case, spaces, hyphens and underscores are ignored |
f ~* ANY ('a', 'b') / f !~* ALL ('a', 'b') | flexibly matches at least one / none of the values |
f ~* ALL (...) / f !~* ANY (...) | one condition per value, joined with AND / OR |
f = NULL / f != NULL | has no value / has a value |
tags.name = NULL / tags.name != NULL | untagged / tagged, the same as costs.tagged = 'false' / 'true' |
Combine conditions with AND, OR and parentheses, nested as deeply as you need. AND binds tighter than OR. Keywords and field names are not case-sensitive; values are, except with ~* and !~*.
Put values in single quotes and write a quote inside a value as two: tags->>'owner' = 'o''neil'. In a LIKE pattern, % is a wildcard only at the start or the end, _ is an ordinary character, and \% is a literal percent sign.
Examples
Costs of two services outside one region:
Code
Production-tagged costs, or anything in a Kubernetes namespace that starts with payments:
Code
A filter written in Vantage VQL, such as costs.provider = 'aws' AND tags.name = 'team' AND tags.value = 'platform', keeps its provider and writes its tag differently in CQL:
Code
Untagged costs, and costs whose team tag is missing:
Code
Costs of one custom provider, named when it was created:
Code
Compute costs of two segments, with their share of shared cost:
Code
Costs of the team Team A, however its tags spell it, in accounts whose name contains prod:
Code
How it behaves
- OR becomes groups. Costfluent reads any nesting of AND and OR as up to 10 alternatives, each a list of conditions joined with AND:
a AND (b OR c)becomes(a AND b) OR (a AND c). A filter holds at most 20 conditions in one alternative and 50 in total. A filter that would pass those limits is refused with a message naming the limit. - Missing values.
= NULLmatches a row whose field is empty, or, for a tag, a row without that tag key.NULLis compared with=and!=only;costs.provideralways has a value,costs.taggedis'true'or'false'andcosts.tag_complianceis'compliant'or'non_compliant', so none of them takes it. - Providers.
costs.providertakes provider keys and is compared with=,!=,INandNOT INonly. A pattern, or a value that is not a key, is refused with a message naming example keys. Every custom provider has the keycustom; tell them apart withcosts.provider_name, which takes patterns like any other field. - FOCUS values.
costs.charge_categoryandcosts.pricing_categoryhold the FOCUS 1.4 values listed above, spelled as listed. Compared with=,!=,INorNOT IN, any other value, such asOnDemandorSpot, is refused with a message naming the values; aLIKEpattern is free text. On-demand prices areStandard, spot pricesDynamic, and reservations and savings plansCommitted, whichcosts.commitment_typetells apart. - Flexible match.
~*removes spaces, tabs, line breaks, hyphens and underscores from the field and from each value and compares them ignoring case, sotags->>'team' ~* 'Team A'matchesTeam A,team-a,team_aandTEAMA, but notteam-ab.!~*keeps every other row, including those without the field or tag key. A value made only of the ignored characters, such as'-', is refused.costs.provider,costs.tagged,costs.tag_complianceandcosts.segmenttake neither~*nor!~*. - Billing period.
costs.billing_periodtakes months writtenYYYY-MM, such as'2026-03', compared with=,!=,INandNOT INonly. Every line has one, so it takes noNULL, and a pattern,~*or a value that is not such a month is refused with a message saying so. The month is read in UTC; Google Cloud states its invoice month as midnight Pacific time, which is still that month in UTC. - Limits. Text is limited to 100,000 characters and to 32 levels of parentheses.
- Segments.
costs.segmenttakes segment ids with=orINonly, in one condition of a filter without OR; select several segments withIN.!=,NOT IN,LIKE,NULL, a second segment condition and OR anywhere in the filter are refused, as is the shared cost bucket, which owns no cost of its own. An id that is not a segment of the workspace, including a deleted segment, is answered as not found. Allocation rules, virtual tag rules and savings measurements cannot use the field. How shared cost enters a segment is in Segments and allocation rules. - Tag compliance.
costs.tag_compliancetakes'compliant'or'non_compliant'with=,!=,INandNOT INonly, and is read against the workspace's tag policy when the report runs, so changing the policy changes what an existing report counts. In a workspace without a policy every row is'compliant'. Allocation rules, virtual tag rules and savings measurements cannot use the field. - Virtual tag rules. A rule's filter cannot use OR, because rules are already alternatives, tried in order. Write each alternative as its own rule with the same value.
- Canonical text. Costfluent shows a filter in one canonical spelling: lowercase field names, uppercase keywords and single spacing. The Public API returns both spellings of any filter from
GET /v1/cost-filters/translate. - No match. A filter whose values match nothing shows the report's usual empty result, not an error. Check the values' spelling and case against the ones a filter clause lists.
- Error messages appear in the console's language; the Public API answers in English.
- Not supported, with the error saying so:
costs.allocationandcosts.marketplace, which have no Costfluent columncosts.charge_type: writecosts.charge_categorytags.nameandtags.valuewith a value: writetags->>'key' = 'value'