---
title: Legacy-to-DQL Reference
slug: dql/YAGtbUIy40FsnPL0Kj4gd
docTags: 
createdAt: 2023-11-14T01:24:15.016Z
---

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

:::hint{type="info"}
In DQL syntax, enclose `string` literals within single quotes (`''`); for example `'blue'` . 
:::

:::hint{type="warning"}
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

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

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

:::VerticalSplitItem
**DQL**

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

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

## Inserting Multiple Documents

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
// Not Supported
```
:::

:::VerticalSplitItem
**DQL**

```javascript
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](docId\:Fw4PWu4BxwmMzieENEkeF).

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

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

:::VerticalSplitItem
**DQL**

```javascript
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.

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

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

:::VerticalSplitItem
**DQL**

```javascript
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

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
await ditto.store
.collection('cars')
.find('color == "blue"')
```
:::

:::VerticalSplitItem
**DQL**

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

## Querying Data by ID

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
await ditto.store
.collection('cars')
.findById('123')
```
:::

:::VerticalSplitItem
**DQL**

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

## Querying Data with Limits

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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

## Querying for Null Values

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
await ditto.store
.collection('cars')
.find('color == null')
```
:::

:::VerticalSplitItem
**DQL**

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

## Querying with Arguments

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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



## Observing Data Changes

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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



# Updating Documents

## Updating a Single Document

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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

## Updating Multiple Documents

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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

## Updating Multiple Fields

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

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

:::VerticalSplitItem
**DQL**

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



# Deleting Documents

## Evicting Documents

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
await ditto.store
.collection('cars')
.find('color == "blue"')
.evict()
```
:::

:::VerticalSplitItem
**DQL**

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

## Deleting Documents

::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
await ditto.store
.collection('cars')
.find('color == "blue"')
.remove()
```
:::

:::VerticalSplitItem
**DQL**

```javascript
// Not Supported (use EVICT)
```
:::
::::





# Syncing Data From Other Peers



::::VerticalSplit{layout="middle"}
:::VerticalSplitItem
**Legacy**

```javascript
ditto.store
.collection('cars')
.find('color == "blue"')
.subscribe()
```
:::

:::VerticalSplitItem
**DQL**

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