​
Creating Documents

In DQL syntax, enclose string literals within single quotes (''); for example 'blue' .

Use single quotes in DQL queries to ensure accuracy. Incorrectly using double quotes (""); for example "blue", may prevent document matching. Currently, Ditto does not throw a warning for this issue.

​
Inserting a Single Document

Legacy

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store
.collection('cars')
.upsert(newCar)

DQL

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:newCar)`,
  { newCar })

​
Inserting Multiple Documents

Legacy

JS
// Not Supported

DQL

JS
const car1 = {
  _id: '123',
  color: 'blue',
}
const car2 = {
  _id: '456',
  color: 'red',
}

await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:car1),(:car2)`,
  { car1, car2 })

​
Inserting Initial/Default Documents

This is the ability to insert documents at time 0. For more information see INSERT with INITIAL DOCUMENTS.

Legacy

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store
.collection('cars')
.upsert(newCar, { writeStrategy: "insertDefaultIfAbsent" })

DQL

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store.execute(`
  INSERT INTO cars
  INITIAL DOCUMENTS (:newCar)`,
  { newCar })

​
Upserting Documents

Legacy supports upserting by default where DQL requires the policy to be explicitly set.

Legacy

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store
.collection('cars')
.upsert(newCar)

DQL

JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:newCar)
  ON ID CONFLICT DO UPDATE`,
  { newCar })

​
Reading Data

​
Querying Data

Legacy

JS
await ditto.store
.collection('cars')
.find('color == "blue"')

DQL

JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)

​
Querying Data by ID

Legacy

JS
await ditto.store
.collection('cars')
.findById('123')

DQL

JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE _id = '123'
  `)

​
Querying Data with Limits

Legacy

JS
await ditto.store
.collection('cars')
.find('color == "blue"')
.limit(10)

DQL

JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  LIMIT 10
  `)

​
Querying for Null Values

Legacy

JS
await ditto.store
.collection('cars')
.find('color == null')

DQL

JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color IS NULL
  `)

​
Querying with Arguments

Legacy

JS
await ditto.store
.collection('cars')
.find(
  'color == $args.color',
  { color: 'blue' })

DQL

JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = :color`,
  { color: 'blue' })

​
Observing Data Changes

Legacy

JS
const observer = ditto.store
.collection('cars')
.find('color = "blue"')
.observeLocal((result, event) => {
    // do something
  })

DQL

JS
ditto.store.registerObserver(`
  SELECT *
  FROM cars
  WHERE color = 'blue'`,
  (result) => {
    // handle change
  })

​
Updating Documents

​
Updating a Single Document

Legacy

JS
await ditto.store
.collection('cars')
.findByID('123')
.update((mutableDoc) => {
  mutableDoc.at('color').set('red')
})

DQL

JS
await ditto.store.execute(`
  UPDATE cars
  SET color = 'red'
  WHERE _id = '123'
  `)

​
Updating Multiple Documents

Legacy

JS
await ditto.store
  .collection('cars')
  .find('color == "blue"')
  .update((documents) => {
    for (const document of documents) {
      document.color = 'red'
    }
  })

DQL

JS
await ditto.store.execute(`
  UPDATE cars
  SET color = 'red'
  WHERE color = 'blue'
  `)

​
Updating Multiple Fields

Legacy

JS
await ditto.store
.collection('cars')
.findByID('123')
.update((mutableDoc) => {
  mutableDoc.at('color').set('red')
  mutableDoc.at('mileage').set(3001)
})

DQL

JS
await ditto.store.execute(`
  UPDATE cars
  SET
    color = 'red',
    mileage = 3001
  WHERE _id = '123'
  `)

​
Deleting Documents

​
Evicting Documents

Legacy

JS
await ditto.store
.collection('cars')
.find('color == "blue"')
.evict()

DQL

JS
await ditto.store.execute(`
  EVICT FROM cars
  WHERE color = 'blue'
  `)

​
Deleting Documents

There are several ways to delete data in Ditto, and you can find more detail about them here.

Removing documents with the below method creates a “tombstone” record which is replicated to indicate something was deleted. This tombstone cannot be removed later, so we recommend only doing this for documents which are no longer present on any small peers.

In the future, this will be replaced by a DELETE command which handles system-wide deletes more cleanly.

Legacy

JS
await ditto.store
.collection('cars')
.find('color == "blue"')
.remove()

DQL

DQL
-- Only available in Big Peer
TOMBSTONE FROM cars WHERE color == "blue"

​
Syncing Data From Other Peers

Legacy

JS
ditto.store
.collection('cars')
.find('color == "blue"')
.subscribe()

DQL

JS
ditto.sync.registerSubscription(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)

Was this page helpful?

Documents and IDs (Legacy)Legacy-to-DQL Adoption Guide