Readable ⇐ Entity

Kind: global class
Extends: Entity

new Readable (spec)

A readable database entity (table or view).

Param Type Description
spec Object An {@linkcode Entity} specification representing a readable object:
spec.db Object A {@linkcode Database}.
spec.name String The table or view's name.
spec.schema String The name of the schema owning the table or view.
spec.columns Object | Array An array of column names, or an object mapping constituent Readable names to their column name arrays.
spec.joins Object A join object.
[spec.is_matview] Boolean Whether the object is a materialized view (default false).

readable.aliasField (field) ⇒ String

Generate a consistent alias for a field belonging to this Readable.

Kind: instance method of Readable
Returns: String - An alias separating schema (if necessary), relation, and field names with double underscores.

Param Type Description
field String The field to alias.

readable.count (conditions, params) ⇒ Promise

Count rows matching criteria. There are two ways to use this method:

  1. find() style: db.mytable.count({field: value});
  2. where() style: db.mytable.count("field=$1", [value]);

Kind: instance method of Readable
Returns: Promise - Row count.

Param Type Description
conditions Object | String A criteria object or SQL predicate.
params Array Prepared statement parameters for use with raw SQL predicates.

readable.countDoc (criteria) ⇒ Promise

Count documents matching criteria. Unlike count, this function only supports criteria objects.

Kind: instance method of Readable
Returns: Promise - Number of matching documents.

Param Type Description
criteria Object A criteria object.

readable.find (criteria, [options]) ⇒ Promise

Find rows matching criteria.

Kind: instance method of Readable
Returns: Promise - An array containing any query results.

Param Type Description
criteria Object | UUID | Number A criteria object or primary key value.
[options] Object Select options.

readable.findDoc ([criteria], [options]) ⇒ Promise

Find a document by searching in the body.

Kind: instance method of Readable
Returns: Promise - An array containing any query results.

Param Type Description
[criteria] Object | UUID | Number A criteria object or primary key value.
[options] Object Select options.

readable.findOne (criteria, [options]) ⇒ Promise

Return a single record.

Kind: instance method of Readable
Returns: Promise - An object representing the (first) record found, or null if no records match.

Param Type Description
criteria Object | UUID | Number A criteria object or primary key value.
[options] Object Select options.

readable.refresh ([concurrently]) ⇒ Promise

Refresh a materialized view.

Kind: instance method of Readable
Returns: Promise - A query with no results.

Param Type Description
[concurrently] Boolean Do it without locking reads.

readable.search (plan, [options], doDocumentProcessing) ⇒ Promise

Perform a full-text search on queryable fields. If options.document is true, looks in the document body fields instead of the table columns.

Kind: instance method of Readable
Returns: Promise - An array containing any query results.

Param Type Description
plan Object Search definition.
plan.fields Array List of the fields to search.
plan.term String Search term.
[plan.parser] String Parse search term as plain (more forgiving than the default), phrase, or websearch.
[plan.tsv] String Unsafely interpolate a prebuilt text search vector instead of using fields.
[plan.where] Object Criteria object to filter results.
[options] Object Select options.
doDocumentProcessing Boolean True to process results as documents.

readable.searchDoc (plan, [options]) ⇒ Promise

Shortcut to perform a full text search on a document table.

Kind: instance method of Readable
Returns: Promise - An array containing any query results.

Param Type Description
plan Object Search definition.
[plan.fields] Array List of the document keys to search.
plan.term String Search term.
[plan.where] Object Criteria object to filter results.
[options] Object Select options.

readable.where (conditions, [params], [options]) ⇒ Promise

Run a query with a raw SQL predicate, eg:

db.mytable.where('id=$1', [123]).then(...);

Kind: instance method of Readable
Returns: Promise - An array containing any query results.

Param Type Description
conditions String A raw SQL predicate.
[params] Array Prepared statement parameters.
[options] Object Select options.

readable.disjoin (criteria, offset, kind) ⇒ String

Build a disjunction (logical OR).

Kind: instance method of Readable
Returns: String - The JOIN condition text, to be stored and interpolated into queries after the ON.

Param Type Description
criteria Object A criteria object.
offset Number Offset prepared statement parameter ordinals.
kind Symbol forJoin, forWhere, or forDoc.

readable.conjoin (criteria, offset, kind) ⇒ String

Build a conjunction (logical AND).

Kind: instance method of Readable
Returns: String - The JOIN condition text, to be stored and interpolated into queries after the ON.

Param Type Description
criteria Object A criteria object.
offset Number Offset prepared statement parameter ordinals.
kind Symbol forJoin, forWhere, or forDoc.

readable.predicate (criteria, offset, kind) ⇒ Object

Create a {predicate, params} object from join or where criteria.

Spread argument is used to disambiguate columns while building compound Readables by prepending the joining relation's alias, e.g. "alias"."field".

Kind: instance method of Readable
Returns: Object - A predicate string and an array of parameters.

Param Type Description
criteria Object Query criteria mapping column names (optionally including operation eg 'my_field <>') to the parameter values. Predicates generated from a criteria object are joined together with $and; an $or key denotes an array of nested criteria objects, the collected predicates from each of which are parenthesized and joined with $or.
offset Number Added to the token index value in the prepared statement (with offset 0, parameters will start $1, $2, $3).
kind Symbol forJoin, forWhere, or forDoc.

readable.findCandidateJoinKeys (parentReadable, parentAlias) ⇒ Array

Find the foreign key relationships which exist between this readable and its parent in a join context.

Kind: instance method of Readable
Returns: Array - A list of foreign key relationships represented as objects mapping fields of this Readable to their corresponding fields in parentReadable.

Param Type Description
parentReadable Readable The readable being joined to.
parentAlias String The alias corresponding to parentReadable in the current join tree.

readable.join (definition) ⇒ Readable

Create a compound Readable by declaring other relations to attach. Queries against the compound Readable will JOIN the attached relations and decompose results into object trees automatically.

Compound Readables are cached. If the same join plan is encountered elsewhere, Massive will pull the compound Readable from the cache instead of processing the definition again.

Kind: instance method of Readable
Returns: Readable - The compound Readable.

Param Type Description
definition Object An object mapping relation paths (optional schema and dot, required name) or aliases to objects defining the join type (inner, left outer, etc); on mapping the foreign column(s) in the relation being joined to the source column(s) in the relation being joined to; and an optional relation path if an alias is used for the key. These objects may be nested.