Skip to main content

match_object_meta

Synopsis​

@match_object_meta(MetadataKey LogicalExpression) -> Boolean

@match_object_meta(MetadataKey InnerFunction) -> Boolean

Description​

Checks if the object's metadata entry matches the provided condition.

info

Available in Contextal Platform 1.0 and later.

Parameters​

The first argument is always the object's metadata key name, which is followed by a logical expression or an inner function regex/iregex/starts_with, if the key's value is of type String.

Return value​

Boolean: true if the metadata key exists and its value matches the condition, false otherwise.

Examples​

@match_object_meta($natural_language == "English")
  • This matches an object, which has a metadata key natural_language and its value is "English"
@match_object_meta($number_of_words > 200)
  • This matches an object, which has a metadata key number_of_words and its value is bigger than 200.
@match_object_meta($url starts_with("https://"))
  • This matches an object, which has a metadata key url and its value starts with the string "https://"

Precise Array Matching​

Assume we have three objects containing an array inside the meta field:

Example Objects​

array: [
    { "key": "name", "value": "John" },
    { "key": "surname", "value": "Smith" }
]
array: [
    { "key": "name", "value": "Bob" },
    { "key": "surname", "value": "John" }
]
array: [
    { "key": "department", "value": "Sales" },
    { "key": "manager", "value": "John" }
]

Finding Objects Containing { "key": "name", "value": "John" }​

Knowing the exact index in the array, we can use the query:

@match_object_meta($array[0].key == "name") && @match_object_meta($array[0].value == "John")

However, this approach is not convenient because the order of elements in the array may differ.

To search for matches in all rows, we can omit the index:

@match_object_meta($array.value == "John")

This query returns all three objects, even though only the first one actually contains { "key": "name", "value": "John" }. This happens because the condition only checks for "value": "John" anywhere in the array, without considering the "key".

A more precise query combining conditions would be:

@match_object_meta($array.key == "name") && @match_object_meta($array.value == "John")

This still does not work correctly, because it matches all objects containing "key": "name" or "value": "John", rather than ensuring they exist together in the same array row.

Precise Row-Level Matching​

ContexQL offers a precise matching method for arrays, and with the following syntax we can ensure conditions are evaluated at the row level:

@match_object_meta($array ? ($key=="name" && $value=="John"))

This query correctly returns only the first object, as it ensures both conditions apply within the same array element. The method works regardless of element order and prevents false positives from partial matches across different rows.