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

# Natural Language Create

`NLQueryCreatorExecutor` creates new records from natural language descriptions. It handles nested entity resolution, file processing, and transactional persistence.

## Basic Usage

```python
from amsdal_ml.ml_models.openai import OpenAIModel
from amsdal_ml.nlquery.creator import NLQueryCreatorExecutor

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

creator = NLQueryCreatorExecutor(llm=llm, queryset=Customer.objects.all())

analysis = await creator.analyze(
    'Create a new customer John Doe, email john@example.com, based in New York'
)
print(analysis.payloads)  # generated field values (list of CreatePayload)

results = await creator.execute(analysis)
```

## How It Works

The create operation follows a 3-phase pipeline:

### Phase 1: Resolution Strategy

The LLM analyzes the query and identifies:

- Which fields to populate
- Whether nested entities need to be resolved (e.g., "assign to the Sales department" requires finding the Department record)
- Which fields are missing required values

### Phase 2: Context Retrieval

For foreign key fields referencing existing records, the executor:

- Searches the database for matching entities
- Resolves references (e.g., "Sales department" → actual Department ID)
- Reports missing references if no match is found

### Phase 3: Payload Synthesis & Persistence

The executor:

- Generates the complete `CreatePayload` with resolved field values
- Validates required fields
- Saves the record within a transaction
- Returns the created records (list)

## CreatePayload

The result includes a `CreatePayload` with:

| Field | Description |
|-------|-------------|
| `fields` | Dict of field names → values |
| `missing_required` | List of required fields that couldn't be determined |

## Authorization

Pass a callback to check permissions before saving:

```python
creator = NLQueryCreatorExecutor(
    llm=llm,
    queryset=Customer.objects.all(),
    on_before_save=my_auth_callback,
)
```

## Document-Oriented Facade

`NLQueryCreator` returns serialized `Document` objects:

```python
from amsdal_ml.nlquery.creator import NLQueryCreator

creator = NLQueryCreator(llm=llm, queryset=Customer.objects.all())
analysis = await creator.analyze('Create customer Jane Smith, email jane@smith.com')
documents = await creator.invoke(analysis)
```
