This project is part of the @thi.ng/umbrella monorepo.

• About
  • Status
  • Planned features
  • Related packages
• Installation
• Dependencies
• API
  • Intersection vs. union queries
  • Query patterns
  • Querying objects
• Authors
• License

Datalog-inspired, optimized pattern/predicate query engine for JS objects & arrays.

This package provides a single higher-order function defQuery(), which takes a number of options to configure query behavior and returns an actual query function. This returned function can then be used for pattern matching of objects and arrays of objects.

STABLE - used in production

Search or submit any issues for this package

Some of the below features are already partially addressed by other thi.ng/umbrella packages, but would benefit from a more unified approach.

• query joins (AND queries)
• optional queries (OR queries)
• result projection
• result aggregation/grouping

• @thi.ng/associative - Alternative Map and Set implementations with customizable equality semantics & supporting operations
• @thi.ng/csv - Customizable, transducer-based CSV parser/object mapper and transformer
• @thi.ng/egf - Extensible Graph Format
• @thi.ng/rstream-query - @thi.ng/rstream based triple store & reactive query engine

yarn add @thi.ng/oquery

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/oquery"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const oquery = await import("@thi.ng/oquery");

Package sizes (gzipped, pre-treeshake): ESM: 1.26 KB

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/defmulti
• @thi.ng/equiv

Generated API docs

Currently, there are 27 unique & optimized query implementations, each based on RDF-style Subject-Predicate-Object triple patterns (only without any similar restrictions on query terms data types), with each of the three terms one of:

• null - wildcard, any non-null (or undefined) value in that position will be selected
• Predicate function - called with all possible terms in that position
• Literal value - for subjects and predicates, this can only be a string or number. For "object" position any value type is allowed
• Array or Set - multiple choices (literals) for given query term

By default, arrays or sets in O(bject) position are matched in an elementwise manner using OR-semantics, i.e. a match succeeds with the first matched element. Since v0.3.0 intersection queries are supported too, i.e. all elements of the given array/set must match for the query to succeed (see examples/differences further below).

The behavior can be chosen via the intersect query option.

Object queries expect an object of the following structure:

{ subj1: { pred1: "obj1", pred2: 2, pred3: ["a", "b"] }, ... }

A concrete example:

const DB = {
    alice: {
        age: 33,
        knows: ["bob", "charlie", "dori"],
        type: "person",
    },
    bob: {
        age: 32,
        knows: ["alice"],
        type: "person",
        spouse: "alice",
    },
    charlie: {
        parent: "alice",
        knows: ["alice", "bob", "dori"],
    },
    dori: {
        knows: ["bob"]
    }
};

To find all answers for the question: Who knows Bob?

// create query w/ custom options
// (options explained further below...)
const query = defQuery({ partial: true });

query(DB, null, "knows", "bob");
// {
//   alice: { knows: ["bob"] },
//   charlie: { knows: ["bob"] }
// }

For each of the 3 query terms, the following IDs are used:

• * = null (wildcard)
• l = literal value (or array/set of literals)
• f = predicate function

Further variations:

(1) If the "subject" term is a literal (or array), then only object(s) for given key value(s) are matched, using the same logic for the other two terms as in the table above.

// Who does Alice know?
query(DB, "alice", "knows", null)
// { alice: { knows: [ 'bob', 'charlie', 'dori' ] } }

(2) If the subject is a predicate, then any top-level keys matching the given predicate will be matched (again using same rules as above for the other query terms).

// Anyone with initial "A" knows Charlie?
query(DB, (s) => s[0] === "a", "knows", "charlie")
// { alice: { knows: [ 'charlie' ] } }

(3) Instead of a root object (like DB), an array of objects can be queried. In this case, only predicate-object patterns are used (no subject terms, aka array indices in this case).

const DBALT = [
  { id: "alice", knows: ["bob", "charlie"] },
  { id: "bob", knows: ["alice"] },
  { id: "charlie", knows: ["alice","bob","dori"] },
];

defQuery()(DBALT, "knows", "alice")
// [
//   { id: 'bob', knows: [ 'alice' ] },
//   { id: 'charlie', knows: [ 'alice', 'bob', 'dori' ] }
// ]

The following example is using the DB object defined further above...

import { defQuery } from "@thi.ng/oquery";

// using partial result objects option for brevity here
const query = defQuery({ partial: true });

// find all subjects with `type = "person"` relationship
query(DB, null, "type", "person");
// { alice: { type: 'person' }, bob: { type: 'person' } }

// everyone w/ given min age
query(DB, null, "age", (age) => age >= 33)
// { alice: { age: 33 } }

// select only subjects with A/B initials
query(DB, (id) => id >= "a" && id < "c", null, null)
// {
//   alice: { age: 33, knows: [ 'bob', 'charlie', 'dori' ], type: 'person' },
//   bob: { age: 32, knows: [ 'alice' ], type: 'person', spouse: 'alice' }
// }

Union vs. intersection queries:

const union = defQuery();

// who knows bob OR charlie?
union(DB, null, "knows", ["bob", "charlie"]);
// {
//   alice: { age: 33, knows: [ 'bob', 'charlie', 'dori' ], type: 'person' },
//   charlie: { parent: 'alice', knows: [ 'alice', 'bob', 'dori' ] },
//   dori: { knows: [ 'bob' ] }
// }

const isec = defQuery({ intersect: true });

// who knows bob AND charlie?
isec(DB, null, "knows", ["bob", "charlie"]);
// {
//   alice: { age: 33, knows: [ 'bob', 'charlie', 'dori' ], type: 'person' }
// }

More query examples in tests...

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-oquery,
  title = "@thi.ng/oquery",
  author = "Karsten Schmidt",
  note = "https://thi.ng/oquery",
  year = 2020
}

© 2020 - 2021 Karsten Schmidt // Apache Software License 2.0