|
| 1 | +JSONPath Querying |
| 2 | +================= |
| 3 | + |
| 4 | +The executor's built-in path walker only splits on ``.`` and indexes — it can't |
| 5 | +do wildcards, recursive descent, or filters, so API/DB responses with arrays are |
| 6 | +awkward to extract from. ``json_query`` adds a focused JSONPath subset over |
| 7 | +already-parsed JSON: |
| 8 | + |
| 9 | +================ =================================================== |
| 10 | +Syntax Meaning |
| 11 | +================ =================================================== |
| 12 | +``$`` root (optional prefix) |
| 13 | +``.name`` member access |
| 14 | +``[n]`` ``[-n]`` list index (negative from the end) |
| 15 | +``*`` ``[*]`` wildcard (all members / elements) |
| 16 | +``..`` recursive descent |
| 17 | +``[?(@.k op v)]`` filter array elements (``op`` ∈ ``== != < <= > >=``) |
| 18 | +================ =================================================== |
| 19 | + |
| 20 | +Pure standard library (``re``); imports no ``PySide6``. |
| 21 | + |
| 22 | +Headless API |
| 23 | +------------ |
| 24 | + |
| 25 | +.. code-block:: python |
| 26 | +
|
| 27 | + from je_auto_control import json_query, json_query_one, json_extract |
| 28 | +
|
| 29 | + json_query(data, "$.store.books[*].title") # every title |
| 30 | + json_query(data, "$.store.books[?(@.price > 8)].title") # filtered |
| 31 | + json_query(data, "$..price") # recursive descent |
| 32 | +
|
| 33 | + json_query_one(data, "$.user.name", default="?") # first match or default |
| 34 | + json_extract(data, {"name": "$.user.name", # mapping -> flat dict |
| 35 | + "first_tag": "$.tags[0]"}) |
| 36 | +
|
| 37 | +``json_query`` returns **all** matches (a list); ``json_query_one`` returns the |
| 38 | +first (or a default); ``json_extract`` runs a ``{key: path}`` mapping into a flat |
| 39 | +dict (first match per path). This is the path engine the existing |
| 40 | +``AC_http_to_var`` / API / DB-row flows were missing. |
| 41 | + |
| 42 | +Executor commands |
| 43 | +----------------- |
| 44 | + |
| 45 | +================================ =================================================== |
| 46 | +Command Effect |
| 47 | +================================ =================================================== |
| 48 | +``AC_json_query`` ``{matches}`` — all values matching a JSONPath. |
| 49 | +``AC_json_extract`` ``{result}`` — a ``{key: path}`` mapping extracted. |
| 50 | +================================ =================================================== |
| 51 | + |
| 52 | +``data`` (and ``mapping``) accept a JSON object or a JSON string (so the visual |
| 53 | +builder works). The same operations are exposed as MCP tools (``ac_json_query`` / |
| 54 | +``ac_json_extract``) and as Script Builder commands under **Data**. |
0 commit comments