🗝️ Add KeyPresent queries

docs/source/reference/queries.md

@@ -19,6 +19,7 @@ Follow the links in the table below for examples specific to each query.
    tiled.queries.Eq
    tiled.queries.NotEq
    tiled.queries.FullText
+   tiled.queries.KeyPresent
    tiled.queries.In
    tiled.queries.Like
    tiled.queries.NotIn

tiled/_tests/test_queries.py

@@ -20,6 +20,7 @@
     FullText,
     In,
     Key,
+    KeyPresent,
     KeysFilter,
     Like,
     NotEq,
@@ -326,6 +327,25 @@ def test_structure_families(client):
     assert set(client.search(StructureFamilyQuery("array"))) == set(mapping)
 
 
+def test_key_present(client):
+    if client.metadata["backend"] == "map":
+        pytest.skip("No 'KeyPresent' support on MapAdapter")
+    # These containers have a "color" key.
+    assert list(client.search(KeyPresent("color"))) == [
+        "full_text_test_case",
+        "full_text_test_case_urple",
+    ]
+    # These are all the containers that do not have a "number" key.
+    assert list(client.search(KeyPresent("number", False))) == [
+        "does_contain_z",
+        "does_not_contain_z",
+        "full_text_test_case",
+        "full_text_test_case_urple",
+        "specs_foo_bar",
+        "specs_foo_bar_baz",
+    ]
+
+
 def test_keys_filter(client):
     expected = ["a", "b", "c"]
     results = client.search(KeysFilter(keys=expected))

tiled/adapters/mapping.py

@@ -28,6 +28,7 @@
     Eq,
     FullText,
     In,
+    KeyPresent,
     KeysFilter,
     NotEq,
     NotIn,
@@ -753,6 +754,28 @@ def notin(query: Any, tree: MapAdapter) -> MapAdapter:
 MapAdapter.register_query(NotIn, notin)
 
 
+def keypresent(query: Any, tree: MapAdapter) -> MapAdapter:
+    """
+
+    Parameters
+    ----------
+    query :
+    tree :
+
+    Returns
+    -------
+
+    """
+    matches = {}
+    for key, value, term in iter_child_metadata(query.key, tree):
+        if term in query.key:
+            matches[key] = value
+    return tree.new_variation(mapping=matches)
+
+
+MapAdapter.register_query(KeyPresent, keypresent)
+
+
 def specs(query: Any, tree: MapAdapter) -> MapAdapter:
     """
 

tiled/catalog/adapter.py

@@ -50,6 +50,7 @@
     Eq,
     FullText,
     In,
+    KeyPresent,
     KeysFilter,
     Like,
     NotEq,
@@ -1431,6 +1432,20 @@ def in_or_not_in(query, tree, method):
     return _IN_OR_NOT_IN_DIALECT_DISPATCH[dialect_name](query, tree, method)
 
 
+def has_key(query, tree):
+    # Functionally in SQLAlchemy 'is not None' does not work as expected
+    if tree.context.engine.url.get_dialect().name == "sqlite":
+        condition = orm.Node.metadata_.op("->")(query.key) != None  # noqa: E711
+    else:
+        keys = query.key.split(".")
+        condition = (
+            orm.Node.metadata_.op("#>")(sql_cast(keys, ARRAY(TEXT)))
+            != None  # noqa: E711
+        )
+    condition = condition if getattr(query, "exists", True) else not_(condition)
+    return tree.new_variation(conditions=tree.conditions + [condition])
+
+
 def keys_filter(query, tree):
     condition = orm.Node.key.in_(query.keys)
     return tree.new_variation(conditions=tree.conditions + [condition])
@@ -1447,6 +1462,7 @@ def structure_family(query, tree):
 CatalogNodeAdapter.register_query(Contains, contains)
 CatalogNodeAdapter.register_query(In, partial(in_or_not_in, method="in_"))
 CatalogNodeAdapter.register_query(NotIn, partial(in_or_not_in, method="not_in"))
+CatalogNodeAdapter.register_query(KeyPresent, has_key)
 CatalogNodeAdapter.register_query(KeysFilter, keys_filter)
 CatalogNodeAdapter.register_query(StructureFamilyQuery, structure_family)
 CatalogNodeAdapter.register_query(SpecsQuery, specs)

tiled/queries.py

@@ -374,6 +374,41 @@ def decode(cls, *, key, value):
         return cls(key=key, value=json.loads(value))
 
 
+@register(name="keypresent")
+@dataclass
+class KeyPresent:
+    """
+    Query to retrieve containers that have a specific key at any level.
+
+    Parameters
+    ----------
+    key : str
+        e.g. "color", "sample.name"
+    exists : bool
+        Set to True by default, but can be set to False to find the inverse
+    Examples
+    --------
+
+    Search for containers that have the key "color"
+
+    >>> c.search(KeyPresent("color"))
+
+    Search for containers that do not have the key "sample.name"
+
+    >>> c.search(KeyPresent("sample.name", exists=False))
+    """
+
+    key: str
+    exists: bool = True
+
+    def encode(self):
+        return {"key": self.key, "exists": self.exists}
+
+    @classmethod
+    def decode(cls, *, key, exists):
+        return cls(key=key, exists=exists)
+
+
 @register(name="like")
 @dataclass
 class Like(NoBool):