Graphs and Queries may have attributes to encode concepts that aren’t expressible in JSON.

• $key, $ref and $chi on both graphs and queries
• $val, $put, $ver and $err on graphs

$key

Specifies a key range on a node, particularly when the keys aren’t strings. These are equivalent:

users: {
  uid1: {
    name: 'Alice'
  }
}

Here, the users node has only one child. When this happens we may skip the array.

users: [{
  $key: 'uid1',
  name: 'Alice'
}]

users: {
  $key: 'uid1',
  name: 'Alice'
}

Pagination uses specially crafted objects as keys, called range keys.

$ref

Refers to a specific node in the tree using its path. In graphs, they are used to specify links, while in queries, they help specify aliases.

Links are similar to symbolic links in a filesystem, and “redirect” queries from one part of the tree to another.

For example, a post object may link to the user who wrote it, or a user object may link to a collection of their posts.

Here, author is a link to a user object, and posts is a link to a collection of post objects.

author: { $ref: 'users.uid1' }

posts: { $ref: [
  'posts',
  { authorId: 'uid1', $all: true }
] }

Aliases allow us to rename parts of a query to make it easier to process the results. This query, for instance, makes a query under comments and renames the result to firstComments.

Here, firstComments is an alias of the comments query.

{
  firstComments: {
    $ref: ['comment', { $first: 2 }],
    title: true
  },
}

Queries can traverse these References.

$chi

Options are additional data interpreted by providers when fulfilling for a read or write operation. For example, authentication credentials may be provided under options. $opt is valid only at the root of a query or change graph tree; it is not valid on result graphs.

Conventionally, read operations support two boolean options, fetch (whether the initial result should be retrieved) and watch (whether change stream should be retrieved). Both are true by default.

$val

By default, Graffy considers JS objects and arrays to be graph nodes. Sometimes, it is useful to store a JS object or array in a Graffy leaf node and treat it as a simple, atomic value: $val does that.

For example, imagine that you are storing some geographic information in a GeoJSON object, within Graffy. As this structure has arrays, and we don’t need to query parts of it using Graffy, this should be stored as a scalar value.

There are two equivalent ways to use $val:

{ worldCoastlines: { $val: true, ...geoJson } }