Legacy Query Language
Legacy-to-DQL Reference

This article covers example mappings from Legacy Query APIs to DQL for basic CRUD operations as well as syncing data with the SDK.
Creating Documents
﻿
﻿
Inserting a Single Document
Legacy
JS
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store
.collection('cars')
.upsert(newCar)
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 })
const newCar = {
  _id: '123',
  color: 'blue',
}

await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:newCar)`,
  { newCar })
﻿
Inserting Multiple Documents
Legacy
JS
// Not Supported
// 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 })
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" })
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 })
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)
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 })
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"')
await ditto.store
.collection('cars')
.find('color == "blue"')
﻿
DQL
JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)
﻿
Querying Data by ID
Legacy
JS
await ditto.store
.collection('cars')
.findById('123')
await ditto.store
.collection('cars')
.findById('123')
﻿
DQL
JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE _id = '123'
  `)
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)
await ditto.store
.collection('cars')
.find('color == "blue"')
.limit(10)
﻿
DQL
JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  LIMIT 10
  `)
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')
await ditto.store
.collection('cars')
.find('color == null')
﻿
DQL
JS
await ditto.store.execute(`
  SELECT *
  FROM cars
  WHERE color IS NULL
  `)
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' })
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' })
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
  })
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
  })
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')
})
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'
  `)
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'
    }
  })
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'
  `)
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)
})
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'
  `)
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()
await ditto.store
.collection('cars')
.find('color == "blue"')
.evict()
﻿
DQL
JS
await ditto.store.execute(`
  EVICT FROM cars
  WHERE color = 'blue'
  `)
await ditto.store.execute(`
  EVICT FROM cars
  WHERE color = 'blue'
  `)
﻿
Deleting Documents
Legacy
JS
await ditto.store
.collection('cars')
.find('color == "blue"')
.remove()
await ditto.store
.collection('cars')
.find('color == "blue"')
.remove()
﻿
DQL
JS
// Not Supported (use EVICT)
// Not Supported (use EVICT)
﻿
﻿
﻿
Syncing Data From Other Peers
﻿
Legacy
JS
ditto.store
.collection('cars')
.find('color == "blue"')
.subscribe()
ditto.store
.collection('cars')
.find('color == "blue"')
.subscribe()
﻿
DQL
JS
ditto.sync.registerSubscription(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)
ditto.sync.registerSubscription(`
  SELECT *
  FROM cars
  WHERE color = 'blue'
  `)
﻿
﻿
Updated 02 Aug 2024
Did this page help you?
Documents and IDs (Legacy)
Legacy-to-DQL Adoption Guide