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

• About
  • Status
  • Planned features
  • Related packages
• Installation
• Dependencies
• API
  • Query patterns
  • Querying objects
• Authors
• License

About

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.

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Planned features

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

Related packages

• @thi.ng/associative - Alternative Map and Set implementations with customizable equality semantics & supporting operations
• @thi.ng/egf - Extensible Graph Format
• @thi.ng/rstream-query - @thi.ng/rstream based triple store & reactive query engine

Installation

yarn add @thi.ng/oquery

// ES module
<script type="module" src="https://unpkg.com/@thi.ng/oquery?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/oquery/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 1.29 KB / CJS: 1.34 KB / UMD: 1.35 KB

Dependencies

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

API

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

Query patterns

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"],
    },
};

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' ] }
// ]

Querying objects

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' } }

// find all who know bob or charlie
query(DB, null, "knows", ["bob", "charlie"])
// { alice: { knows: [ 'bob', 'charlie' ] }, charlie: { knows: [ 'bob' ] } }

// 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' }
// }

More query examples in tests...

Authors

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
}

License

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