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

# Tables

> Modèle de données des tables Retriever : colonnes, valeurs, statuts de cellule, qualification, fit de ligne et import de listes.

Une table contient des entreprises ou des contacts. Les runs la créent ou l'enrichissent ; vous pouvez aussi importer vos propres listes.

## Table vivante et table figée

|         | Table vivante                                    | Table figée                                  |
| ------- | ------------------------------------------------ | -------------------------------------------- |
| Lecture | `GET /v1/tables/{id}/rows`                       | `GET /v1/runs/{id}/output/tables/{key}/rows` |
| Origine | Workspace                                        | Contrat `output` d'un run                    |
| Contenu | Change quand un run ou un utilisateur la modifie | Ne change plus                               |

## Colonnes

`GET /v1/tables/{id}` renvoie les colonnes dans l'ordre :

```json theme={null}
{
  "id": "tbl_001",
  "workspace_id": "ws_001",
  "name": "Fintechs FR",
  "columns": [
    { "key": "company_name", "name": "Entreprise", "kind": "field" },
    { "key": "is_b2b", "name": "B2B ?", "kind": "qualification", "qualification": {} }
  ],
  "row_count": 30,
  "links": { "self": "/v1/tables/tbl_001", "rows": "/v1/tables/tbl_001/rows" }
}
```

Utilisez `key` dans votre code ; `name` sert à l'affichage.

## Lignes

```json theme={null}
{
  "id": "row_001",
  "values": { "company_name": "Acme", "is_b2b": true },
  "cells": {
    "company_name": { "status": "done" },
    "is_b2b": { "status": "done", "qualification": { "result": "match", "reason": "Offre B2B." } }
  },
  "fit": { "status": "qualified" }
}
```

| Champ    | Contenu                                                                                            |
| -------- | -------------------------------------------------------------------------------------------------- |
| `values` | Données métier, par clé de colonne. Objets, tableaux, booléens et `null` restent des valeurs JSON. |
| `cells`  | Métadonnées de chaque cellule : statut, qualification, citations, dépendances périmées.            |
| `fit`    | Verdict de qualification de la ligne.                                                              |

| Valeur                         | Possibilités                                      |
| ------------------------------ | ------------------------------------------------- |
| `cells.*.status`               | `empty`, `running`, `done`, `failed`, `no_result` |
| `cells.*.qualification.result` | `match`, `no_match`, `unsure`                     |
| `fit.status`                   | `qualified`, `disqualified`, `unknown`            |

<Note>
  Une valeur `null` ne suffit pas : lisez `status` pour distinguer « pas trouvé » (`no_result`) de « en cours » (`running`).
</Note>

## Importer une liste

`POST /v1/workspaces/{id}/tables` crée une table avec vos colonnes et vos lignes, en une seule transaction : une erreur annule tout l'import.

| Champ     | Requis               | Règle                                                                           |
| --------- | -------------------- | ------------------------------------------------------------------------------- |
| `name`    | oui                  | Non vide.                                                                       |
| `columns` | oui, au moins 1      | Chaque colonne a `key` et `name`. Clés uniques, non vides, sans espaces autour. |
| `rows`    | non, `[]` par défaut | Objets dont chaque clé est une colonne déclarée. Valeurs JSON quelconques.      |

* Une propriété absente devient `null`. L'ordre des lignes et des colonnes est conservé.
* Les colonnes créées sont de type `field`.
* Une table ne reçoit pas de lignes après sa création : créez une nouvelle table par lot.
* La création n'est pas idempotente : chaque appel crée une nouvelle table.

Voir [Enrichir une liste de votre CRM](/recipes/enrich-crm-list) pour un exemple complet.