bokeh.core.query

The query module provides functions for searching collections of Bokeh models for instances that match specified criteria.

class EQ

Predicate to test if property values are equal to some value.

Construct and EQ predicate as a dict with EQ as the key, and a value to compare against.

# matches any models with .size == 10
dict(size={ EQ: 10 })

class GEQ

Predicate to test if property values are greater than or equal to some value.

Construct and GEQ predicate as a dict with GEQ as the key, and a value to compare against.

# matches any models with .size >= 10
dict(size={ GEQ: 10 })

class GT

Predicate to test if property values are greater than some value.

Construct and GT predicate as a dict with GT as the key, and a value to compare against.

# matches any models with .size > 10
dict(size={ GT: 10 })

class IN

Predicate to test if property values are in some collection.

Construct and IN predicate as a dict with IN as the key, and a list of values to check against.

# matches any models with .name in ['a', 'mycircle', 'myline']
dict(name={ IN: ['a', 'mycircle', 'myline'] })

class LEQ

Predicate to test if property values are less than or equal to some value.

Construct and LEQ predicate as a dict with LEQ as the key, and a value to compare against.

# matches any models with .size <= 10
dict(size={ LEQ: 10 })

class LT

Predicate to test if property values are less than some value.

Construct and LT predicate as a dict with LT as the key, and a value to compare against.

# matches any models with .size < 10
dict(size={ LT: 10 })

class NEQ

Predicate to test if property values are unequal to some value.

Construct and NEQ predicate as a dict with NEQ as the key, and a value to compare against.

# matches any models with .size != 10
dict(size={ NEQ: 10 })

class OR

Form disjunctions from other query predicates.

Construct an OR expression by making a dict with OR as the key, and a list of other query expressions as the value:

# matches any Axis subclasses or models with .name == "mycircle"
{ OR: [dict(type=Axis), dict(name="mycircle")] }

find(objs: Iterable[Model], selector: dict[Union[str, type['_Operator']], Any]) → Iterable[Model]

Query a collection of Bokeh models and yield any that match the a selector.

Parameters:

• obj (Model) – object to test

• selector (JSON-like) – query selector

Yields:

Model – objects that match the query

Queries are specified as selectors similar to MongoDB style query selectors, as described for match().

Examples

# find all objects with type Grid
find(p.references(), {'type': Grid})

# find all objects with type Grid or Axis
find(p.references(), {OR: [
    {'type': Grid}, {'type': Axis}
]})

# same query, using IN operator
find(p.references(), {'type': {IN: [Grid, Axis]}})

is_single_string_selector(selector: dict[Union[str, type['_Operator']], Any], field: str) → bool

Whether a selector is a simple single field, e.g. {name: "foo"}

Parameters:

• selector (JSON-like) – query selector

• field (str) – field name to check for

Returns

bool

match(obj: Model, selector: dict[Union[str, type['_Operator']], Any]) → bool

Test whether a given Bokeh model matches a given selector.

Parameters:

• obj (Model) – object to test

• selector (JSON-like) – query selector

Returns:

True if the object matches, False otherwise

Return type:

bool

In general, the selectors have the form:

{ attrname : predicate }

Where a predicate is constructed from the operators EQ, GT, etc. and is used to compare against values of model attributes named attrname.

For example:

>>> from bokeh.plotting import figure
>>> p = figure(width=400)

>>> match(p, {'width': {EQ: 400}})
True

>>> match(p, {'width': {GT: 500}})
False

There are two selector keys that are handled especially. The first is ‘type’, which will do an isinstance check:

>>> from bokeh.plotting import figure
>>> from bokeh.models import Axis
>>> p = figure()

>>> match(p.xaxis[0], {'type': Axis})
True

>>> match(p.title, {'type': Axis})
False

There is also a 'tags' attribute that Model objects have, that is a list of user-supplied values. The 'tags' selector key can be used to query against this list of tags. An object matches if any of the tags in the selector match any of the tags on the object:

>>> from bokeh.plotting import figure
>>> p = figure(tags = ["my plot", 10])

>>> match(p, {'tags': "my plot"})
True

>>> match(p, {'tags': ["my plot", 10]})
True

>>> match(p, {'tags': ["foo"]})
False