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, you'll need to use db.query or create an SQL script file.

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.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.isPkSearch(criteria) ⇒ Boolean

Determine whether criteria represent a search by primary key. If a number or uuid are passed, it is assumed to be a primary key value; if an object, it must have only one key, which must specify the primary key column.

Kind: instance method of Writable
Returns: Boolean - True if the criteria represent a primary key search.

Param Type Description
criteria Object | String | Number A criteria object or primitive to test.

writable.search(plan, [options]) ⇒ 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.where] Object Criteria object to filter results.
[options] Object Select options.

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.