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
And
clausesNumeric, 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. AndClause
s 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;