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

# Preparing a file for import

To upload data into Maestra Platform, your file needs the right format and encoding. This guide walks through the requirements and shows how to save the file correctly from common spreadsheet apps.

## File requirements

| Parameter      | Value                                                  |
| -------------- | ------------------------------------------------------ |
| Format         | `.csv` or `.txt`                                       |
| Encoding       | `UTF-8`, `UTF-8 with BOM`, or `Windows-1251`           |
| Delimiter      | Any (commonly comma `,` or semicolon `;`)              |
| Text qualifier | Any (double quotes `"` recommended)                    |
| Size           | Up to 1.5 GB                                           |
| File name      | Up to 400 characters; cannot contain `\ / : * ? " < >` |

### File format

Maestra accepts two formats:

* `.csv` (recommended)
* `.txt`

<Warning>
  Other spreadsheet formats ( e.g.,`.xlsx`, `.xls`, `.ods`) are not supported.
</Warning>

**How to check the format:** look at the file extension after the dot — `customers.csv` works, `customers.xlsx` does not.

<Frame>
  <img src="https://mintcdn.com/maestraio/8C7OSkMNXHs2tnzg/images/import-file-recommendations-type.png?fit=max&auto=format&n=8C7OSkMNXHs2tnzg&q=85&s=3b5404a39b653d6d2111e129f07d48d3" alt="Import File Recommendations Type" width="502" height="238" data-path="images/import-file-recommendations-type.png" />
</Frame>

<Note>
  **Don't see file extensions?**

  * **Windows:** in File Explorer, go to **View** and enable **File name extensions**.
  * **macOS:** in Finder, go to **Settings → Advanced** and enable **Show all filename extensions**.

  Or check the file type in its properties (right-click → **Properties** on Windows, or right-click → **Get Info** / `Cmd + I` on macOS).
</Note>

### Encoding

Encoding tells your computer how to interpret letters and symbols. If the file's encoding doesn't match what Maestra Platform expects, names may appear as garbled characters like `Ðнна Иванова` in the preview.

**Fix:** re-save the file as `UTF-8` using the instructions in [How to save the file correctly](#how-to-save-the-file-correctly).

### Column delimiter

In `.csv` and `.txt` files, data is stored as plain text and columns are separated by a delimiter character.

Maestra Platform supports any delimiter. The most common ones are:

| Delimiter                  | What it looks like              |
| -------------------------- | ------------------------------- |
| **Comma `,`**(recommended) | `Smith,John,+15551234567`       |
| **Semicolon `;`**          | `Smith;John;+15551234567`       |
| **Tab `\t`**               | `Smith    John    +15551234567` |

**How to check the delimiter:**

1. Open the file in Notepad (Windows) or TextEdit (macOS).
2. Look at the first data row.
3. Note the character separating the values.

<Frame caption="Example of an import file using a comma(,) delimiter">
  <img src="https://mintcdn.com/maestraio/LYx-7dDw4fnYkSJ7/images/phot.jpg?fit=max&auto=format&n=LYx-7dDw4fnYkSJ7&q=85&s=1ad219904f9e1700a56756a1142354ba" alt="Phot" width="1280" height="264" data-path="images/phot.jpg" />
</Frame>

<Tip>
  If the import preview shows all your data crammed into a single column, just pick the correct delimiter in the upload settings — the columns will redistribute automatically.
</Tip>

### Text qualifier

A qualifier is a character that wraps values containing special symbols (like a comma inside an address, or a line break). Without it, those values would be misread as multiple columns.

<Info>
  The recommended qualifier is double quotes `"`.
</Info>

**Example:**

Without a qualifier:

```text theme={null}
Name,Address,Phone
John,Boston, MA, 5 Main St,+15551234567
```

The delimiter `;` also appears inside the address. Maestra Platform would see **4 columns** instead of 3 and throw an error.

With a qualifier:

```text theme={null}
Name,Address,Phone
John,"Boston, MA, 5 Main St",+15551234567
```

**How to check the qualifier:**

1. Open the file in Notepad or TextEdit.
2. Look at rows where values contain punctuation (addresses, product descriptions, reviews).
3. If those values are wrapped in `"..."`, the qualifier is `"`. If not, no qualifier is in use.

### File size

The limit is **1.5 GB per file**, which is plenty for almost any task.

**How to check file size:**

* **Windows:** right-click the file → **Properties** → **Size**.
* **macOS:** right-click → **Get Info** / `Cmd + I`.

**What to do if your file is larger than 1.5 GB:**

1. **Split the file into parts** (by region, segment, date range, etc.) and upload each part as a separate import.
2. **Remove duplicate columns and rows.**

<Tip>
  Smaller files (under 200–500 MB) upload and process faster. For recurring imports, break large exports into smaller chunks.
</Tip>

## How to save the file correctly

Pick the tool you use.

<Accordion title="Microsoft Excel">
  <Steps>
    <Step title="Open or prepare your file" />

    <Step title="Choose File → Save As" />

    <Step title="Pick a folder" />

    <Step title="Enter a file name" />

    <Step title="In the file type dropdown, choose one of">
      * CSV (comma delimited) — recommended
      * **CSV UTF-8 (comma delimited)**
      * Text (tab-delimited)

      <Frame>
        <img src="https://mintcdn.com/maestraio/8C7OSkMNXHs2tnzg/images/Screenshot-2026-05-21-121122.png?fit=max&auto=format&n=8C7OSkMNXHs2tnzg&q=85&s=3a993f13e83a8299a416b074235fa53a" alt="Screenshot 2026 05 21 121122" width="1027" height="696" data-path="images/Screenshot-2026-05-21-121122.png" />
      </Frame>
    </Step>

    <Step title="Click Save" />
  </Steps>
</Accordion>

<Accordion title="LibreOffice">
  <Steps>
    <Step title="Open or prepare your file" />

    <Step title="Choose File → Save As" />

    <Step title="Pick a folder and file name" />

    <Step title="In the file type dropdown, choose Text CSV (.csv)" />

    <Step title="Enable Edit filter settings to set encoding, delimiter, or qualifier" />

    <Step title="Click Save" />

    <Step title="In the dialog that appears, set">
      * **Character set:** `UTF-8`
      * **Field delimiter:** `,`(comma)
      * **String delimiter:** `"` (double quote)
    </Step>

    <Step title="Click OK" />
  </Steps>
</Accordion>

<Accordion title="Google Sheets">
  Google Sheets always exports `.csv` as `UTF-8` with a comma delimiter. There's no way to change the delimiter or qualifier from the UI.

  <Steps>
    <Step title="Open the file in Google Sheets" />

    <Step title="Choose File → Download → Comma-separated values (.csv)">
      <Frame>
        <img src="https://mintcdn.com/maestraio/8C7OSkMNXHs2tnzg/images/Screenshot_2.png?fit=max&auto=format&n=8C7OSkMNXHs2tnzg&q=85&s=0deb87c4c9c52f1a0843416eeae62c43" alt="Screenshot 2" width="1283" height="1218" data-path="images/Screenshot_2.png" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

## Common problems

### Non-Latin characters appear as "?" or gibberish

The file is saved in an unsupported encoding. Re-save it as UTF-8 (or Windows-1251) using the instructions above.

### Data lands in a single column on upload

Maestra Platform couldn't detect the delimiter. In the upload settings, manually pick the delimiter (and qualifier if needed) — the preview will redistribute columns automatically.

If that doesn't help, re-save the file with a different delimiter.

### The file is rejected on upload

* Check the extension — only `.csv` and `.txt` are supported.
* Check the file name — it cannot contain forbidden characters.
* Check the size — it must be under 1.5 GB.