JSONPath Filters
This page documents filters included with the Liquid JSONPath package. See the filter reference for details of all standard filters. Also see the Python JSONPath docs for JSONPath selector syntax.
find
<object> | find: <string> -> <list>
Return the result of applying a jsonpath string to the input value. The input value should be a list (or any sequence) or a dict (or any mapping).
{{ site | find: '$.users.*.name' | join: ' ' }}
If the following data was assigned to a variable called site
:
{
"users": [
{
"name": "Sue",
"score": 100
},
{
"name": "John",
"score": 86
},
{
"name": "Sally",
"score": 84
},
{
"name": "Jane",
"score": 55
}
]
}
We'd get an output like this:
Sue John Sally Jane
Options
The find
filter defaults to returning an undefined instance when given anything other than a mapping or sequence as its input value. You can change this behavior by setting the default
argument to one of Default.EMPTY
, Default.RAISE
or Default.UNDEFINED
when registering find
with an environment.
from liquid import Environment
from liquid_jsonpath import Default
from liquid_jsonpath import Find
env = Environment()
env.add_filter("find", Find(default=Default.RAISE))
# ...
Default.RAISE
will raise a FilterArgumentError
when given an unacceptable input value or JSONPath string, and Default.EMPTY
will simply return an empty list instead.
Customizing JSONPath
The find
filter uses a JSONPathEnvironment
with its default configuration. You can replace the JSONPathEnvironment
used by find
by subclassing liquid_jsonpath.Find
and setting the jsonpath_class
class attribute.
from jsonpath import JSONPathEnvironment
from liquid_jsonpath import Find
class MyJSONPathEnv(JSONPathEnvironment):
root_token = "^" # silly example
class MyFindFilter(Find):
jsonpath_class = MyJSONPathEnv
env = Environment()
env.add_filter("find", MyFindFilter())