Reporting

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
(costs.provider = 'aws' AND costs.service = 'Amazon Elastic Compute Cloud') OR costs.region LIKE 'eu-%'

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, gcp or kubernetes, the same key the Public API returns. The provider's name, such as Amazon Web Services, is a separate field, costs.provider_name.

Write a filter in a report

  1. Open a report under Cost reports and choose Edit as text beside Add filter, above the chart.
  2. 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.
  3. 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

CQLFilter field
costs.providerProvider
costs.provider_nameProvider name
costs.account_idSub-account
costs.account_nameSub-account name: the name the bill gives the account
costs.serviceService
costs.regionRegion
costs.resource_nameResource
costs.resource_groupResource group: the Azure resource group, read from the resource id
costs.charge_categoryCharge category: Usage, Purchase, Tax, Credit or Adjustment
costs.clusterCluster
costs.namespaceNamespace
costs.provider_account_idBilling account
costs.provider_account_nameBilling account name: the name the bill gives the account, never a connection's name a report may show beside its id
costs.categoryService category
costs.subcategoryService subcategory
costs.usage_unitUsage unit
costs.charge_classCharge class: Correction for a charge that corrects an earlier period
costs.resource_idResource ID
costs.commitment_statusCommitment status: Used or Unused
costs.commitment_typeCommitment type: SavingsPlan, ReservedInstance or CommittedUseDiscount
costs.commitment_idCommitment: the provider's id for it, such as a Savings Plan's ARN
costs.pricing_categoryPricing category: Standard, Dynamic, Committed or Other, and none on a tax
costs.skuSKU: the provider's label for what was billed, or the SKU id of a line without one
costs.sku_idSKU ID: the provider's id for what was billed
costs.operationOperation: the AWS operation billed, such as RunInstances
costs.charge_descriptionCharge description: the bill's own text for the line
costs.resource_typeResource type: the kind of resource billed, as the provider names it
costs.product_familyProduct family: Azure's service family, such as Compute
costs.invoice_idInvoice ID: the provider's invoice the line is billed on
costs.invoice_issuerInvoice issuer: the provider's legal entity that invoices the line, such as Amazon Web Services EMEA SARL
costs.billing_periodBilling period: the month invoiced, written YYYY-MM, such as '2026-03'
costs.taggedTagged: '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_complianceTag 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.segmentSegment, named by its id (seg_...): the cost your allocation rules assign to the segment, plus its share of shared cost

Operators

WriteMeans
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 != NULLhas no value / has a value
tags.name = NULL / tags.name != NULLuntagged / 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
costs.service IN ('Amazon Elastic Compute Cloud', 'Amazon Simple Storage Service') AND costs.region != 'us-east-1'

Production-tagged costs, or anything in a Kubernetes namespace that starts with payments:

Code
tags->>'Environment' = 'production' OR costs.namespace LIKE 'payments%'

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
costs.provider = 'aws' AND tags->>'team' = 'platform'

Untagged costs, and costs whose team tag is missing:

Code
tags.name = NULL OR (costs.category = 'Compute' AND tags->>'team' = NULL)

Costs of one custom provider, named when it was created:

Code
costs.provider = 'custom' AND costs.provider_name = 'Snowflake'

Compute costs of two segments, with their share of shared cost:

Code
costs.segment IN ('seg_...', 'seg_...') AND costs.category = 'Compute'

Costs of the team Team A, however its tags spell it, in accounts whose name contains prod:

Code
tags->>'team' ~* 'Team A' AND costs.account_name LIKE '%prod%'

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. = NULL matches a row whose field is empty, or, for a tag, a row without that tag key. NULL is compared with = and != only; costs.provider always has a value, costs.tagged is 'true' or 'false' and costs.tag_compliance is 'compliant' or 'non_compliant', so none of them takes it.
  • Providers. costs.provider takes provider keys and is compared with =, !=, IN and NOT IN only. A pattern, or a value that is not a key, is refused with a message naming example keys. Every custom provider has the key custom; tell them apart with costs.provider_name, which takes patterns like any other field.
  • FOCUS values. costs.charge_category and costs.pricing_category hold the FOCUS 1.4 values listed above, spelled as listed. Compared with =, !=, IN or NOT IN, any other value, such as OnDemand or Spot, is refused with a message naming the values; a LIKE pattern is free text. On-demand prices are Standard, spot prices Dynamic, and reservations and savings plans Committed, which costs.commitment_type tells apart.
  • Flexible match. ~* removes spaces, tabs, line breaks, hyphens and underscores from the field and from each value and compares them ignoring case, so tags->>'team' ~* 'Team A' matches Team A, team-a, team_a and TEAMA, but not team-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_compliance and costs.segment take neither ~* nor !~*.
  • Billing period. costs.billing_period takes months written YYYY-MM, such as '2026-03', compared with =, !=, IN and NOT IN only. Every line has one, so it takes no NULL, 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.segment takes segment ids with = or IN only, in one condition of a filter without OR; select several segments with IN. !=, 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_compliance takes 'compliant' or 'non_compliant' with =, !=, IN and NOT IN only, 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.allocation and costs.marketplace, which have no Costfluent column
    • costs.charge_type: write costs.charge_category
    • tags.name and tags.value with a value: write tags->>'key' = 'value'