Metadata can be assigned to Zones, DNS names and RRSets.

We can use metadata filter expressions to filter results based on their metadata

Illustrative examples

We start the guide with illustrative examples, and later present a detailed, strict definition of the filters.

We present two illustrative scenarios, to show how metadata filters could be useful.

Scenario 1: Filtering DNS names by "product"

Assume you have DNS names that are tagged with metadata with the "product" key, that can be set to various values, one of them being "static".

Metadata filters can be used to filter the results based on these values.

Here are some examples:

Filter records with metadata { "product": "static" }

{ "op": "exact", "key": "product", "value": "static" }

Filter records without the product key

{ "op": "not_exists", "key": "product" }

Filter with the product key set to some other value, like { "product": "not-static" }:

{ "op": "differs", "key": "product", "value": "static" }

Filter records without the product key, or its value is different from static, like { "product": "not-static" }:

{
  "or": [
    { "op": "not_exists", "key": "product" },
    { "op": "differs", "key": "product", "value": "static" }
  ]
}

Scenario 2: Filter RRSets by expiration

Suppose RRSets are tagged with metadata key last_updated that holds the date when the RRSet was last updated.

Filter RRSets updated past a 1999-01-01:

{ "op": "gt", "key": "last_updated", "value": "1999-01-01T00:00:00-00:00" }

Filter RRSets updated past a 1999-01-01 up to 2005-12-31:

{
  "and": [
    { "op": "gt", "key": "last_updated", "value": "1999-01-01T00:00:00-00:00" },
    { "op": "le", "key": "last_updated", "value": "2005-12-31T00:00:00-00:00" }
  ]
}

A more general, detailed explanation

The metadata expression format.

The metadata filter expression is a JSON string, defined by the Expression type.
It is used to filter out results based on their metadata.

We support conditions that operate in textual, numeric, or datetime values.

For example, the expression { "op": "exact", "key": "key1", "value": "value1" }
will only yield results with a metadata key named key1 that contains the value value1.

For example, the expression { "op": "lt", "key": "key2", "value": 10 }
will only yield results with a metadata key named key2 that contains a numeric value less than 10.

Textual conditions

A Textual condition is defined by the TextCondition type:

type TextCondition = {
  op: TextOp;
  key: string;
  value: string;
};

A Textual condition can only be used with the exact, contains or differs operators.

type TextOp = "exact" | "contains" | "differs";

These operations enforce that the key exists.

Key conditions

A Key condition is defined by the KeyCondition type:

type KeyCondition = {
  op: KeyOp;
  key: string;
};

A Key condition can be used with the exists and not_exists operators:

type KeyOp = "exists" | "not_exists";

The exist operation match any metadata with the key, and can be used to filter results without constraining its value.

Numeric and datetime conditions

Numeric and datetime conditions are defined by the OrdinalCondition type:

type OrdinalCondition = {
  op: OrdinalOp;
  key: string;
  value: Ordinal;
};

Numeric values can be any JSON number value.
Datetime must be RFC 3339 date strings.

type Ordinal = number | Datetime;
type Datetime = string;

Numeric and Datetime values can be used with the following equality and comparison operators:

type OrdinalOp = "eq" | "lt" | "le" | "gt" | "ge" | "neq";

These operations enforce that the key exists.

`And` clauses

Numeric, datetime and textual conditions can be combined using and and or clauses.
The AndClause combines one or more Condition, and only yields results where all the conditions are true.

type Condition = OrdinalCondition | TextCondition | KeyCondition;
type AndClause = { and: Condition[] };

Example:

{
    "and": [
        { "op" : "contains", "key": "key1", "value": "value1" },
        { "op" : "exact" , "key": "key2", "value": "value2" }
    ]
}

Or clauses

The OrClause combines one or more Condition, and only yields results if any of the conditions are true.

type OrClause = { or: (AndClause | Condition)[] };

Example:

{
    "or": [
        { "op" : "contains", "key": "key1", "value": "value1" },
        { "op" : "exact" , "key": "key2", "value": "value2" }
    ]
}

Nested clauses

We support limited nesting. AndClauses can be nested inside of an AndClause.

Example:

{
    "or": [
        { "op" : "contains", "key": "key1", "value": "value1" },
        { "and": [
            { "op" : "contains", "key": "key2", "value": "value2" },
            { "op" : "exact" , "key": "key3", "value": "value3" }
        ] }
    ]
}

A complete Expression can be formed by a single Condition, and AndClause, or and OrClause, nested or not.

type Expression = AndClause | OrClause | Condition;