> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# EVICT

> DQL language syntax for evicting documents locally

<Info>
  To permanently delete a document from a collection see [`DELETE`](/dql/delete).
</Info>

```sql DQL theme={null}
EVICT FROM your_collection_name
USE IDS [ids]
WHERE [condition]
LIMIT [limit]
OFFSET [offset]
ORDER BY [order by]
RETURNING [projection]
```

<img src="https://mintcdn.com/ditto-248bc0d1/4WlyZ5cmeURK3o9P/images/dql/EvictOrTombstone.svg?fit=max&auto=format&n=4WlyZ5cmeURK3o9P&q=85&s=ea032e649efb0e094956289c000b2ff3" alt="EVICT Syntax Diagram" width="901" height="359" data-path="images/dql/EvictOrTombstone.svg" />

In this syntax:

* `your_collection_name` is the name of the collection from which you want to retrieve the data.
* `[ids]` represents the document IDs to evict, given as a parameter or a literal list, rather than selecting documents with a `WHERE` predicate (optional).
* `[condition]` represents the condition or criteria that determine which documents should be evicted from the local peer.
* `[limit]` represents the maximum number of documents that should be evicted
* `[offset]` represents the offset from 0 that should be used for the eviction query, in practice this should be rarely used
* `[order by]` represents the path within a document to use to order the dataset and order (`ASC` or `DESC`)
* `[projection]` returns fields or expressions taken from the evicted documents (optional). See [RETURNING](/dql/returning).

## Examples of Evicting Documents

Here, documents from the `cars` collection that have the document ID `123` get removed from the Ditto store:

```sql DQL theme={null}
EVICT FROM cars
WHERE _id = '123'
```

As another example, the following snippet, once executed, results in the eviction of documents with timestamps greater than a certain value:

```sql DQL theme={null}
EVICT FROM cars
WHERE some_time_stamp > 1699888298000
```

## Evicting Documents by ID

<Warning>
  `USE IDS` on `EVICT` is available in SDK 5.1 and later.
</Warning>

The optional `USE IDS` clause names the documents to evict by ID, instead of selecting them with a `WHERE` predicate. The IDs may be supplied as a literal list or as a query parameter:

```sql DQL theme={null}
-- Literal list of IDs
EVICT FROM cars USE IDS '123', '456'

-- IDs supplied as a parameter
EVICT FROM cars USE IDS :ids
```

## EVICT with RETURNING

<Warning>
  `RETURNING` is available in SDK 5.1 and later.
</Warning>

Add a `RETURNING` clause to get back the evicted documents, as they were immediately before removal, rather than just the IDs of the documents that were evicted:

```sql DQL theme={null}
-- Return the complete evicted documents
EVICT FROM cars
USE IDS '123'
RETURNING *

-- Return a count of the documents evicted
EVICT FROM cars
WHERE some_time_stamp > 1699888298000
RETURNING COUNT(*) AS evicted
```

For the full projection rules, aggregate support and the restrictions that apply, see [RETURNING](/dql/returning).

## Removing Data from Ditto Server

Removing data from a distributed database is a difficult problem, and memory management requires careful consideration of both subscriptions and evictions.

Note that any data evicted from Ditto Server will reappear if it exists on any device running the Ditto SDK connected to Ditto Server.

To permanently remove the data, you must first ensure the data is no longer subscribed to, and is already evicted, by any connected devices running the Ditto SDK. For specifics on evicting and deleting documents in all Ditto SDKs and to learn more about our recommended strategies, see [`SDK>CRUD>Removing Documents`](/sdk/latest/crud/delete/).

Alternatively, data can be tombstoned from Ditto Server using the legacy API. See: [Writing: HTTP (Legacy)](/cloud/http-api/legacy/writing-http-legacy#remove).


## Related topics

- [Ditto Query Language Overview](/dql/dql.md)
- [Removing Documents](/sdk/v4/crud/delete.md)
- [Device Storage Management](/sdk/latest/sync/device-storage-management.md)