Logseq CLI Datascript Query Implementation Plan

Goal: Add a logseq-cli query subcommand that runs a Datascript query via db-worker-node and returns the raw datascript-query result shape. Architecture: The CLI will parse a query form from arguments, call db-worker-node using the existing /v1/invoke transport with :thread-api/q, and return whatever datascript-query returns without normalization. Architecture: No new db-worker-node HTTP endpoints are required because :thread-api/q already exists in the worker thread API. Tech Stack: ClojureScript, babashka.cli, Datascript, db-worker-node HTTP transport. Related: Relates to docs/agent-guide/012-logseq-cli-graph-storage.md.

Problem statement

The current logseq-cli does not expose a query subcommand for running Datascript queries against a graph. Users need a CLI command that executes a Datascript query and returns the same result shape as datascript-query for scripting and downstream tooling. The solution should follow the existing logseq-cli and db-worker-node invocation patterns so it works with the current daemon and transport.

Testing Plan

I will add an integration test that creates a graph, inserts blocks, runs the new query subcommand, and asserts that the returned IDs match the expected block IDs. I will add a unit test that validates query argument parsing, including invalid EDN, missing query text, and optional inputs parsing. I will add a unit test that verifies the query command returns the same shape as datascript-query without transformation. I will follow @test-driven-development and write the failing tests before implementing behavior.

NOTE: I will write all tests before I add any implementation behavior.

Plan

Create a new command module at src/main/logseq/cli/command/query.cljs that defines the query command spec and action builder. Use --query for the Datascript query form and --inputs for the optional EDN inputs vector, and parse them with cljs.reader/read-string or logseq.common.util/safe-read-string with error handling. Return a structured action map that includes :type :query, :repo, :query, and :inputs to keep execution isolated from parsing. Register the new command in src/main/logseq/cli/commands.cljs and include it in the command table so help output includes query. Update src/main/logseq/cli/main.cljs usage text to include query in the command list. Implement execution in src/main/logseq/cli/command/query.cljs using logseq.cli.transport/invoke with :thread-api/q and args [repo [query & inputs]]. Return the raw Datascript result as-is, matching datascript-query output across human, json, and edn formats. Add formatting in src/main/logseq/cli/format.cljs for :query to render the raw result in human output and pass-through for json or edn output. Add command-level validation in src/main/logseq/cli/commands.cljs to return a missing-query error when no query is supplied. Update src/test/logseq/cli/commands_test.cljs to expect query in help output and to validate parse errors for missing query or invalid input. Add a CLI integration test in src/test/logseq/cli/integration_test.cljs that uses run-cli to execute query and verifies IDs in JSON output. Confirm that no db-worker-node changes are required by verifying that :thread-api/q continues to accept the same argument shape in src/main/frontend/worker/db_core.cljs.

Edge cases

A query string that cannot be read as EDN should return a clear invalid-options error and a non-zero exit code. A query that returns no results should return an empty result with a successful status. Queries with :in parameters should work when --inputs supplies the matching values in order.

Testing Details

The integration test will create a graph, add known blocks, run a query that finds those blocks, and verify that the output matches the datascript-query result shape. The unit tests will assert that parsing rejects invalid EDN for --inputs, that a missing query produces a :missing-query error, and that query execution returns raw results unchanged.

Implementation Details

Add a new command module at src/main/logseq/cli/command/query.cljs.
Add command entries in src/main/logseq/cli/commands.cljs.
Add output formatting in src/main/logseq/cli/format.cljs.
Update usage text in src/main/logseq/cli/main.cljs.
Use transport/invoke with :thread-api/q and [repo [query & inputs]].
Return datascript-query results without transformation.
Keep all argument parsing and validation inside query command module using --query and --inputs.
Keep db-worker-node changes to zero unless a new worker API is required.
Add custom-queries to cli.edn for storing pre-defined Datascript queries that the CLI can list and run by name.
Add built-in queries that appear in the query list alongside custom queries.

Optional inputs should support default values in cli.edn, and built-in queries should ship with reasonable defaults for their optional inputs (required inputs can omit defaults).

block-search (search-title)

[:find [?e ...]
       :in $ ?search-title
       :where
       [?e :block/title ?title]
       [(clojure.string/lower-case ?title) ?title-lower-case]
       [(clojure.string/include? ?title-lower-case ?search-title)]]

task-search (search-status, ?search-title, ?recent-days)

;; Modify this query so search-title and recent-days are optional parameters.
;; ?now-ms is injected by the CLI so users don't need to pass it (and should be hidden in query list output).
;; Example: logseq query --name task-search --inputs '["doing"]'
[:find [?e ...]
       :in $ ?search-status ?search-title ?recent-days ?now-ms
       :where
       [?e :block/title ?title]
       [?e :logseq.property/status ?s]
       [?s :db/ident ?status-ident]
       [(= ?status-ident ?search-status)]
       [(clojure.string/lower-case ?title) ?title-lower-case]
       (or-join [?search-title ?title-lower-case]
                [(nil? ?search-title)]
                [(clojure.string/blank? ?search-title)]
                (and [(clojure.string/lower-case ?search-title) ?search-title-lower-case]
                     [(clojure.string/include? ?title-lower-case ?search-title-lower-case)]))
       [(get-else $ ?e :block/updated-at 0) ?updated-at]
       (or
        [(nil? ?recent-days)]
        (and [(number? ?recent-days)]
             [(<= ?recent-days 0)])
        (and [(number? ?recent-days)]
             [(>= ?updated-at (- ?now-ms (* ?recent-days 86400000)))]) )]

cli.edn query shape

Represent queries as a map keyed by query name. Keep the query form as EDN data (not a string) so it can be read directly. Optional fields like :doc and :inputs are included to help with listing and UX. :inputs should allow optional inputs to declare default values that are used when the CLI caller omits them. Internal inputs like ?now-ms should be hidden from query list output.

Suggested :inputs shapes:

["search-status" "?search-title" "?recent-days"] (legacy string-only form)
[{:name "search-status"} {:name "?search-title" :default nil} {:name "?recent-days" :default nil}] (explicit defaults)

Example:

{:custom-queries
 {"block-search"
  {:doc "Find blocks by title substring (case-insensitive)."
   :inputs ["search-title"]
   :query [:find [?e ...]
           :in $ ?search-title
           :where
           [?e :block/title ?title]
           [(clojure.string/lower-case ?title) ?title-lower-case]
           [(clojure.string/include? ?title-lower-case ?search-title)]]}

  "task-search"
  {:doc "Find tasks by status, optional title substring, optional recent-days."
   :inputs [{:name "search-status"}
            {:name "?search-title" :default nil}
            {:name "?recent-days" :default nil}
            ;; ?now-ms is internal; CLI fills it with current ms and query list should hide it.
            {:name "?now-ms" :default :now-ms}]
   :query [:find [?e ...]
           :in $ ?search-status ?search-title ?recent-days ?now-ms
           :where
           [?e :block/title ?title]
           [?e :logseq.property/status ?s]
           [?s :db/ident ?status-ident]
           [(= ?status-ident ?search-status)]
           [(clojure.string/lower-case ?title) ?title-lower-case]
           (or-join [?search-title ?title-lower-case]
                    [(nil? ?search-title)]
                    [(clojure.string/blank? ?search-title)]
                    (and [(clojure.string/lower-case ?search-title) ?search-title-lower-case]
                         [(clojure.string/include? ?title-lower-case ?search-title-lower-case)]))
           [(get-else $ ?e :block/updated-at 0) ?updated-at]
           (or
            [(nil? ?recent-days)]
            (and [(number? ?recent-days)]
                 [(<= ?recent-days 0)])
            (and [(number? ?recent-days)]
                 [(>= ?updated-at (- ?now-ms (* ?recent-days 86400000)))]) )]}}}

Notes:

Built-in queries live in code but should be merged into the same map shape when listing or resolving by name.
:inputs is optional metadata for CLI help. It does not affect execution.

Question

Use --query and --inputs options for the query subcommand. Output should mirror datascript-query for scripting stability.

9.2 KiB Raw Blame History