Tags – dbzero

`def tags(*objects: Memo | QueryObject, passive: bool = False) -> ObjectTagManager`

Open SourceStandard

Get a tag manager interface for given Memo objects or, in dbzero-pro, live query results.

Parameters

*objects Memo | QueryObject
One or more Memo objects to manage tags for. Passing a live QueryObject, such as db0.find(...), enables set-based tagging in dbzero-pro. dbzero-procommercial edition
passive bool, default False dbzero-procommercial edition If True, subsequent add() calls through this manager create passive tags. Passive tags are queryable, but do not keep the tagged object alive. The passive option has no effect on remove().

Returns

An ObjectTagManager interface for the given memo objects or query targets. The manager has the following methods:

add(self, *tag: Union[Tag, Iterable[Tag]]):
Add one or more tags to the managed objects. Can be passed as individual tags, or collections of tags.
remove(self, *tag: Union[Tag, Iterable[Tag]]):
Remove one or more tags associated with the object(s).

Passive tags require at least one positive non-passive predicate when queried, such as a memo type, a regular tag, an enum tag, or an anchored query. For example, db0.find(Document, "passive-tag") is valid, while db0.find("passive-tag") raises.

Set-based tagging is a dbzero-pro feature. Query targets must be live dbzero queries. Empty query results are valid and update nothing, but snapshot queries are read-only and cannot be used as tag targets.

Examples

Adding a single tag

You can easily add a single string tag to an object.

import dbzero as db0
 
@db0.memo
class Book:
    def __init__(self, title):
        self.title = title
 
book = Book("The Hitchhiker's Guide to the Galaxy")
db0.tags(book).add("sci-fi")
 
# You can now find this book using the tag
sci_fi_books = list(db0.find("sci-fi"))
assert len(sci_fi_books) == 1

Adding multiple tags from a list

The .add() method accepts iterables, so you can add multiple tags at once from a list or tuple.

import dbzero as db0
 
@db0.memo
class Task:
    def __init__(self, description):
        self.description = description
 
task = Task("Write API documentation")
db0.tags(task).add(["docs", "urgent", "writing"])
 
# Find the task by a combination of its tags
urgent_writing_tasks = list(db0.find("urgent", "writing"))
assert len(urgent_writing_tasks) == 1

Removing tags from multiple objects

The tags() method can accept multiple explicit objects, allowing you to perform batch operations.

import dbzero as db0
 
@db0.memo
class Product:
    def __init__(self, name):
        self.name = name
 
product1 = Product("Laptop")
product2 = Product("Mouse")
 
# Add a "sale" tag to both products
db0.tags(product1, product2).add("sale")
assert len(list(db0.find("sale"))) == 2
 
# Later, remove the "sale" tag from both
db0.tags(product1, product2).remove("sale")
assert len(list(db0.find("sale"))) == 0

Set-based tagging

dbzero-procommercial edition

Pass a live find() result to tag or untag every object matched by that query in one optimized operation. This is faster than looping over large query results in Python.

import dbzero as db0
 
overdue_active = db0.find(Invoice, "active", "overdue")
db0.tags(overdue_active).add("needs-review")
 
review_queue = list(db0.find(Invoice, "needs-review"))
 
db0.tags(db0.find("import-session-2026-06")).remove("import-session-2026-06")

You can combine direct objects and query targets:

db0.tags(priority_document, db0.find(Document, "source")).add("audit-scope")

Set-based tagging is a mutating operation. It is rejected inside db0.read_only() and when the target comes from a snapshot query.

Adding passive tags

dbzero-procommercial edition

Use passive=True when a tag should be searchable without controlling object lifetime.

import dbzero as db0
 
@db0.memo
class Document:
    def __init__(self, title):
        self.title = title
 
document = Document("Security report")
 
db0.tags(document, passive=True).add("visible-to-current-user")
 
# Use a type or another positive non-passive predicate to anchor the query.
visible_documents = list(db0.find(Document, "visible-to-current-user"))
assert visible_documents == [document]

Adding passive tags to query results

dbzero-procommercial edition

The tags() function can target query results, which is useful for set-based classification.

active_documents = db0.find(Document, "active")
db0.tags(active_documents, passive=True).add(["needs-review", "visible-to-current-user"])
 
review_queue = list(db0.find(Document, "needs-review"))

Removing passive tags

dbzero-procommercial edition

Remove passive tags with the normal remove() call. The removal manager does not need passive=True.

db0.tags(document).remove("visible-to-current-user")
assert list(db0.find(Document, "visible-to-current-user")) == []

split_by touch