Data Sources & Adapters

Registering sources

registerSource pairs an in-memory value with a name. It does not copy or convert anything; it is a constant-time operation, so you can register large structures freely.

db.registerSource(['users'], usersArray);
db.registerSource(['crm', 'invoices'], invoicesArray); // namespaced name
db.registerSource(['social'], graph);

The name is an array of parts, which lets you namespace sources. Anything can be registered (an array, an object, a DOM document, a graph) because it is the language's data adapter that decides how to read it.

Data adapters

An adapter is the bridge between a language and the concrete shape of your data. Each provided language ships with a sensible default, and each can be pointed at a different shape by supplying your own adapter in the language's config.

Language	Default adapter	Expects
SQL	ObjectDataAdapter	array of objects; property = column
Cypher	GraphologyDataAdapter	a Graphology graph
XQuery	DomDataAdapter	a DOM document / XML tree

SQL: object rows, or your own accessor

By default SQL treats each array element as a row and each property as a column. To read differently-shaped rows (say, Map-backed rows) supply an adapter with a createColumnAccessor:

const db = new DortDB({
  mainLang: SQL({
    adapter: {
      createColumnAccessor: (prop) => (row: Map<string, unknown>) =>
        row.get(prop),
    },
  }),
  optimizer: { rules: defaultRules },
});

db.registerSource(
  ['users'],
  [
    new Map([
      ['name', 'Alice'],
      ['age', 30],
    ]),
    new Map([
      ['name', 'Bob'],
      ['age', 25],
    ]),
  ],
);

db.query('SELECT name, age FROM users WHERE age > 30');
// data: [{ name: 'Alice', age: 30 }]

Cypher: the graph adapter

The default Graphology adapter expects node labels and edge types under the gaLabelsOrType symbol key (see Cypher Overview). Because graphs can be represented in many ways, the adapter is the seam where you would plug in a different graph representation.

XQuery: DOM, or another tree

XQuery's DomDataAdapter targets DOM/XML. In the browser the global document is used automatically; in Node you pass a document from a DOM implementation. The adapter is also the mechanism by which XQuery can be retargeted at other tree-shaped data instead of DOM. See XQuery Overview.

Writing an adapter

Adapters are a first-class extension point. The interfaces differ per language (SQLDataAdapter, XQueryDataAdapter, CypherDataAdapter). See the API reference for the exact members, and Extending DortDB for how adapters fit into the broader extension model.