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

# Exporting results with INTO

> Export query results to a file using the INTO clause. Supports CSV, JSON, XML, XLSX, ODS, and NDJSON output.

The `INTO` clause writes query results to a file. You call it on the result of `->execute()`, passing a target file query that describes the output format and path.

## Fluent API

Pass a `FileQuery` object or a raw file query string to `->into()`. The method returns a `FileQuery` with effective defaults applied, which you can use to read the written file back:

```php theme={null}
use FQL\Query\FileQuery;
use FQL\Query\Provider;
use FQL\Enum\Operator;

// Using a FileQuery object
$fileQuery = Provider::fromFileQuery('json(./data/products.json).data.products')
    ->select('name', 'price')
    ->where('price', Operator::GREATER_THAN_OR_EQUAL, 300)
    ->execute()
    ->into(new FileQuery('csv(./exports/products.csv)'));

// Using a string shorthand
$fileQuery = Provider::fromFileQuery('json(./data/products.json).data.products')
    ->select('name', 'price')
    ->execute()
    ->into('json(./exports/products.json).root.items');

// Read the written file back using the returned FileQuery
$readBack = Provider::fromFileQuery((string) $fileQuery)
    ->selectAll()
    ->execute();
```

## FQL syntax

Place `INTO` after the `FROM` clause (and any `WHERE`, `ORDER BY`, etc.):

```sql theme={null}
SELECT name, price
FROM csv(./data/products-utf-8.csv).*
INTO csv(./exports/products.csv)
```

`INTO` uses the same file query syntax as `FROM`:

```
format(pathToFile).query
```

## Output format path semantics

The `.query` part of the file query has different meanings depending on the output format. When the query is omitted or set to `*`, each writer applies a sensible default:

| Format     | `.query` meaning                                                                               | Default (when omitted or `*`) | Example       |
| ---------- | ---------------------------------------------------------------------------------------------- | ----------------------------- | ------------- |
| CSV        | Ignored                                                                                        | `*`                           | —             |
| NDJSON     | Ignored                                                                                        | `*`                           | —             |
| JSON       | Nested key path for the output array. `*` or omitted writes a flat array.                      | `*` (flat array)              | `.root.items` |
| XML        | `ROOT.ROW` — root element name and row element name                                            | `rows.row`                    | `.SHOP.ITEM`  |
| XLSX / ODS | `SheetName.StartCell` — sheet name and top-left cell. `*` uses the first sheet starting at A1. | First sheet from A1           | `.Sheet1.B4`  |

## Examples

### Export to CSV

```php theme={null}
use FQL\Query\Provider;

$fileQuery = Provider::fromFileQuery('json(./data/products.json).data.products')
    ->select('name', 'price')
    ->orderBy('price')->asc()
    ->execute()
    ->into('csv(./exports/products.csv)');
// $fileQuery->query is '*'
```

### Export to JSON

```php theme={null}
use FQL\Query\Provider;

$fileQuery = Provider::fromFileQuery('xml(./data/feed.xml).SHOP.SHOPITEM')
    ->select('NAME', 'PRICE')
    ->execute()
    ->into('json(./exports/items.json).root.items');
// $fileQuery->query is 'root.items'
```

### Export to XML

```php theme={null}
use FQL\Query\Provider;

$fileQuery = Provider::fromFileQuery('csv(./data/products.csv).*')
    ->selectAll()
    ->execute()
    ->into('xml(./exports/products.xml).SHOP.ITEM');
// $fileQuery->query is 'SHOP.ITEM'
```

### Export to XLSX

```php theme={null}
use FQL\Query\Provider;

$fileQuery = Provider::fromFileQuery('json(./data/products.json).data.products')
    ->selectAll()
    ->execute()
    ->into('xlsx(./exports/products.xlsx).Sheet1.A1');
// $fileQuery->query is 'Sheet1.A1'
```

## Format-specific behavior

### XLSX and ODS

Exported spreadsheets write the first row as bold column headers automatically. The header row contains the field names from your query.

### JSON

When the query path is `*` or omitted, JSON output writes a flat array at the root level. Specifying a dotted path (e.g. `.root.items`) nests the array under the corresponding keys.

## Writer defaults

When you call `into()`, the writer for the target format applies a default query path if none is specified. The `into()` method returns a `FileQuery` object that includes the effective query, so you can use it to read back the written file without guessing the path:

```php theme={null}
$fileQuery = $results->into('csv(output/report.csv)');

// The returned FileQuery has the effective query applied (e.g. '*' for CSV)
$readBack = \FQL\Query\Provider::fromFileQuery((string) $fileQuery)
    ->selectAll()
    ->execute();
```

If you implement a custom `Writer`, your class must provide a `getFileQuery(): FileQuery` method that returns the `FileQuery` with any default query applied.

## File handling behavior

<Note>
  If the target file already exists, FiQueLa throws a `FileAlreadyExistsException` and does **not** overwrite it. To export again, delete or rename the existing file first.
</Note>

Missing output directories are created automatically — you do not need to create them beforehand.