---
title: "NL Delete"
amsdal_docs:
  target: framework/plugins/amsdal-ml/nl-delete.md
  nav_title: Delete
  nav_section: Framework
  nav_path: ["Plugins & Extensions", "ML", "Natural Language CRUD"]
  nav_order: 4
---

# Natural Language Delete

`NLQueryDeleterExecutor` deletes records matching natural language descriptions. It includes a preview step to avoid accidental deletions.

## Basic Usage

```python
from amsdal_ml.ml_models.openai import OpenAIModel
from amsdal_ml.nlquery.deleter import NLQueryDeleterExecutor

llm = OpenAIModel(model_name='gpt-5.1')
await llm.setup()

deleter = NLQueryDeleterExecutor(llm=llm, queryset=Customer.objects.all())

analysis = await deleter.analyze('Delete inactive customers from 2023')
print(analysis.total)     # number of records to delete

deleted = await deleter.execute(analysis)
```

## How It Works

The delete operation follows a 2-phase pipeline:

### Phase 1: Split

The LLM derives a filter query from the delete instruction (e.g., "Delete inactive customers from 2023" → filter by `is_active=False` and `created_at` in 2023).

### Phase 2: Analysis & Execution

The executor:

- Runs the filter query to find matching records
- Returns a preview of affected records
- Executes deletion within a transaction

## Preview Before Delete

Use `analyze()` to preview which records will be deleted:

```python
deleter = NLQueryDeleterExecutor(llm=llm, queryset=Customer.objects.all())

analysis = await deleter.analyze('Delete all test customers')

print(f'Records to delete: {analysis.total}')
for record in analysis.records:
    print(f'  {record}')

# Only execute if confirmed
if confirmed:
    deleted = await deleter.execute(analysis)
```

## Authorization

Pass a callback to check permissions before deleting:

```python
deleter = NLQueryDeleterExecutor(
    llm=llm,
    queryset=Customer.objects.all(),
    on_before_delete=my_auth_callback,
)
```

## Document-Oriented Facade

```python
from amsdal_ml.nlquery.deleter import NLQueryDeleter

deleter = NLQueryDeleter(llm=llm, queryset=Customer.objects.all())
analysis = await deleter.analyze('Remove archived customers')
documents = await deleter.invoke(analysis)
```
