Writable ⇐ Entity

Kind: global class
Extends: Entity, Readable

new Writable (spec)

A database table or other writable object.

Param Type Description
spec Object An {@linkcode Entity} specification representing a table:
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.
spec.pk String The table's primary key column.

writable.getPkCriteria (record) ⇒ Object

Attempts to assemble primary key criteria for a record object representing a row in this table. The criteria must include the full primary key, and must not invoke any operations.

Kind: instance method of Writable
Returns: Object - The successfully assembled criteria, or null if primary key information is incomplete or invalid.

Param Type Description
record Object The record to evaluate.

writable.insert (data, [options]) ⇒ Promise

Insert a record or records into the table.

Kind: instance method of Writable
Returns: Promise - If passed a record object, the record as inserted (with default or autogenerated values set); if passed an array, an array containing the inserted records.

Param Type Description
data Object | Array A record or records to insert.
[options] Object Insert options.

writable.update (criteria, changes, [options]) ⇒ Promise

Update a record with a criteria object and a map of changed fields to their new values.

Kind: instance method of Writable
Returns: Promise - If updating a single record by its primary key, the modified record; otherwise, an array containing any modified records.

Param Type Description
criteria String | Number | Object Primary key of the record, or a criteria object.
changes Object A map of columns to their new values.
[options] Object Update options.

writable.save (record, [options]) ⇒ Promise

Saves an object. If the object does not include a value for the table's primary key, this will emit an INSERT to create a new record; if it does contain the primary key it will emit an UPDATE for the existing record.

Either way, the newest available version of the record will be returned.

This is not a true Postgres upsert! If you need the behavior of ON CONFLICT DO UPDATE, look into the onConflictUpdate option.

Kind: instance method of Writable
Returns: Promise - The inserted or updated record object.

Param Type Description
record Object The record to upsert.
[options] Object Insert/update options.

writable.destroy (criteria, [options]) ⇒ Promise

Delete a record or records.

Kind: instance method of Writable
Returns: Promise - For a primary key, the deleted record; for a criteria object, an array containing all deleted records.

Param Type Description
criteria Object A criteria object or primary key.
[options] Object Delete options.

writable.saveDoc (doc) ⇒ Promise

Save a document to the database. This function will create or replace the entire document body.

Kind: instance method of Writable
Returns: Promise - The updated document.

Param Type Description
doc Object The document to persist.

writable.saveDocs (docs) ⇒ Promise

Save documents to the database. This function will create or replace the entire document body for each document.

Kind: instance method of Writable
Returns: Promise - The updated documents.

Param Type Description
docs Object The documents to persist.

writable.updateDoc (criteria, changes, [options]) ⇒ Promise

Update a document, adding new information and changing existing information. This function can be used with any JSON field, not just document tables; however, only document tables can use criteria objects which directly reference document fields.

If calling updateDoc with a criteria object for a non-document table, the criteria will be tested against the entire row (as opposed to the document body as it is for document tables). To test elements of the JSON field in a non-document table with a criteria object, use a JSON path string.

Kind: instance method of Writable
Returns: Promise - If modifying a document table, the document; otherwise, the modified row.

Param Type Description
criteria String | Number | Object Primary key of the document, or a criteria object.
changes Object Changes to apply.
[options] Object Update options.
[options.body] String Override the "body" JSON field to affect.

writable.aliasField (field) ⇒ String

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

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

Param Type Description
field String The field to alias.

writable.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 Writable
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.

writable.countDoc (criteria) ⇒ Promise

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

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

Param Type Description
criteria Object A criteria object.

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

Find rows matching criteria.

Kind: instance method of Writable
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.

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

Find a document by searching in the body.

Kind: instance method of Writable
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.

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

Return a single record.

Kind: instance method of Writable
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.

writable.refresh ([concurrently]) ⇒ Promise

Refresh a materialized view.

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

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

writable.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 Writable
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.

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

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

Kind: instance method of Writable
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.

writable.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 Writable
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.

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

Build a disjunction (logical OR).

Kind: instance method of Writable
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.

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

Build a conjunction (logical AND).

Kind: instance method of Writable
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.

writable.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 Writable
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.

writable.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 Writable
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.

writable.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 Writable
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.