mutating data

title: Mutating Data

Mutating Data

"Mutating" is a fancy word for "Changing", and this section deals with how to insert, update, and delete data from the database using tabel ORM.

.insert

.insert(...args)

Can be used to insert either a single row, or an array of rows in a table. Returns a Promise that resolves to the inserted row in the case of single insert, and an array of rows in the case of multiple inserts. If the timestamps prop of the table is set to true, or to custom timestamps(see table-definitions-full-config), timestamps will be appended to the supplied values. If you have set autoId table-prop to true, or are generating primary-keys at database level using auto-increment ids, the returned row will also contain the primary-key.

---

Insert One:

const post = await table('posts').insert({title: 'foo', body: ...});

Insert Many:

const posts = await table('posts').insert([
  {title: 'foo', body: ...},
  {title: 'bar', body: ...},
  {title: 'baz', body: ...}
]);

---

.update

.update(...args)

Used to update either a single row, or to perform a batch-update on the set of rows scoped by the query-chain preceding the .update(...) method call. If the timestamps prop of the table is set to true, will take care of updating the updated_at column(or whatever custom timestamp field you have set for this purpose in the table-definition). Examples below:

Update using key-condition: .update(keyCondition, values={}) Appends a whereKey clause to the query chain before performing an update-query. Returns a Promise that resolves to the updated row scoped by the supplied keyCondition.

async function updatePost(post, data={}) {
  return await table('posts').update(post.id, data);
}

Batch Update: .update(values={}) Performs an update on all the rows scoped by the query-chain that precedes the call to .update(values={}). Returns a Promise.

async function archivePostsBeforeDate(date) {
  return await table('posts').where('created_at', '<', date).update({is_archived: true});
}

---

.delete

.delete(...args)

.del(...args) (shorthand, kept for legacy reasons)

Used to delete rows from the database. Returns a Promise. Can be called in several different ways.

Delete set of rows scoped by the query-chain: .delete()

async function deletePostsOlderThan(date) {
  return await table('posts').where('created_at', '<', date).delete();
}

Delete using primary key: .delete(keyCondition) The keyCondition argument is same as the one used in .whereKey clause.

async function deletePostById(postId) {
  return await table('posts').delete(postId);
}

Delete using .where arguments: .delete(...args)

async function deleteArchivedPosts() {
  return await table('posts').delete('is_archived', true);
}

---

Next > Processing Data