Import et export de données

Vue d’ensemble

Rebase inclut des outils intégrés d’importation et d’exportation de données accessibles directement depuis le panneau d’administration. L’importation prend en charge les fichiers CSV, JSON et Excel avec un assistant de mappage de colonnes. L’exportation prend en charge les formats CSV et JSON avec des champs calculés optionnels.

Les deux fonctionnalités sont disponibles sur chaque collection. L’exportation peut être configurée par collection avec des champs calculés, ou désactivée avec exportable: false ; l’importation ne peut pas être désactivée par collection.

Importer des données

Comment importer

1. Ouvrez une collection dans le panneau d’administration
2. Cliquez sur le bouton Import dans la barre d’outils
3. Sélectionnez ou glissez-déposez votre fichier
4. Mappez les colonnes du fichier aux propriétés de la collection
5. Prévisualisez les données, y compris les valeurs qui ne peuvent pas être converties
6. Cliquez sur Save data pour écrire les lignes

Formats pris en charge

Format	Extensions	Remarques
CSV	.csv	Détection automatique des délimiteurs
JSON	.json	Attend un tableau d’objets
Excel	.xlsx	Lit la première feuille

Mappage des colonnes

L’assistant d’importation tente automatiquement de faire correspondre les colonnes du fichier aux propriétés de la collection par leur nom. Vous pouvez ajuster manuellement les correspondances avant d’importer :

• Les correspondances exactes sont mappées automatiquement (par ex. name → name)
• Les colonnes non reconnues peuvent être mappées manuellement ou ignorées
• La conversion de type transforme chaque cellule dans le type de la propriété à laquelle elle est associée, mais uniquement lorsque rien n’est perdu (voir ci-dessous)

Conversion de type

Une cellule n’est convertie que lorsque le type de la propriété peut contenir exactement ce qu’elle indique :

Type de propriété	Convertit	Ne convertit pas
Nombre	12, -3.5, 10.00, 1e3	02134 (un zéro initial serait perdu), les nombres de plus de 15 chiffres significatifs, 1,234, $5.00, 12%, N/A
Booléen	true/false, yes/no, y/n, 1/0, quelle que soit la casse	tout le reste
Date	ISO 8601 (2024-01-05, 2024-01-05T10:00:00Z), dates en toutes lettres (5 Jan 2024), 05/01/2024, secondes ou millisecondes epoch	un texte qui ne désigne aucune date
Géopoint	l’objet que l’exportation écrit, {"latitude": 41.9, "longitude": 12.5}, ou son JSON dans une cellule CSV	tout le reste, ou une coordonnée hors limites
Map sans champs déclarés	un objet, ou son JSON dans une cellule CSV	tout le reste
Vecteur	une liste de nombres ([0.1, 0.2], 0.1, 0.2), ou le {"value": [0.1, 0.2]} de l’exportation	une liste contenant autre chose qu’un nombre

Une date sans heure correspond à ce jour-là en UTC. Pour les dates écrites 05/01/2024, c’est la colonne qui décide de l’ordre : un premier nombre supérieur à 12 fait de la colonne un format jour-mois, un second nombre supérieur à 12 en fait un format mois-jour. Quand une colonne ne le précise jamais, c’est la locale du navigateur qui décide, et quand elle contient les deux ordres, une date que l’un ou l’autre ordre pourrait lire n’est pas convertie.

Une cellule vide n’est pas une valeur : elle ne définit rien, et la valeur par défaut choisie pour cette propriété s’applique.

Un fichier exporté depuis une collection se réimporte avec les mêmes valeurs, en CSV comme en JSON. Une map avec des champs déclarés se lit avec une colonne par champ (address.street), comme l’exportation l’écrit ; toute autre valeur, y compris un géopoint ou une map clé-valeur, tient en une colonne. Un nombre epoch compris entre -100,000,000,000 et 100,000,000,000 est lu comme des secondes : une date comprise entre le 31 octobre 1966 et le 3 mars 1973 exportée en timestamp ne revient donc pas à l’identique, exportez ces dates en texte. Un champ d’heure du jour lit un nombre inférieur à un jour (86,400,000) comme les millisecondes depuis minuit que l’exportation écrit.

Valeurs qui ne peuvent pas être importées

L’aperçu liste chaque cellule qui ne se convertit pas, par colonne, avec leur nombre et les premières d’entre elles par ligne et par raison. Ces cellules sont laissées vides dans les lignes importées ; rien n’est transformé en 0, false ou une valeur vide sans être listé. Revenez en arrière pour associer la colonne à une autre propriété, ou corrigez le fichier et téléchargez-le à nouveau.

Les propres règles de la collection — champs obligatoires, options d’énumération, valeurs uniques — sont vérifiées par le serveur au fur et à mesure que les lignes sont écrites, par lots pouvant atteindre 500 lignes (moins lorsque les lignes sont larges, afin qu’une requête reste sous environ 1 Mo). Un lot est enregistré en entier ou pas du tout. Si une ligne est refusée, l’importation s’arrête et la désigne ; les lots qui la précèdent sont déjà enregistrés, et Retry reprend à partir de la première ligne du lot de la ligne refusée.

Une ligne dont l’id existe déjà dans la collection met à jour cet enregistrement : les colonnes présentes dans le fichier sont écrites, les autres conservent leurs valeurs stockées, si bien qu’un fichier id,price réévalue des produits existants sans répéter leurs champs obligatoires. Une nouvelle ligne exige toujours tous les champs obligatoires. Un lot qui mêle mises à jour et nouvelles lignes est écrit en deux requêtes, de sorte qu’une nouvelle ligne refusée peut laisser les mises à jour de ce lot enregistrées ; Retry les réécrit avec les mêmes valeurs.

Importer des utilisateurs

Une nouvelle ligne dans la collection des utilisateurs est une création d’utilisateur : une colonne password est hachée, jamais stockée telle quelle, et une ligne qui n’en a pas reçoit un mot de passe généré ou une invitation, comme lorsqu’un administrateur ajoute un utilisateur. Les mots de passe d’un tel fichier ont généralement été définis selon les règles d’un autre système : l’import demande donc au serveur d’ignorer la politique de mot de passe pour ces lignes. Le serveur n’accepte que si vous êtes administrateur ; toute autre personne qui importe des utilisateurs est soumise à la politique, et un mot de passe faible arrête l’import avec WEAK_PASSWORD.

Créer une collection à partir d’un fichier

Lorsque vous créez une collection à partir d’un fichier, le type de chaque colonne est déduit de ses valeurs. Une colonne n’est un nombre que si chacune de ses valeurs est un nombre, ou un texte qui se convertit en un nombre exactement, si bien qu’une colonne de codes postaux, de codes produits à zéros initiaux, de longs SKU ou de numéros de téléphone reste du texte. Une colonne qui mélange les types (nombres et mots, booléens et nombres) est du texte. Les cellules vides ne comptent pas, si bien qu’une colonne majoritairement vide n’est pas marquée comme obligatoire. Une colonne de nombres entiers dont le nom se termine par un mot indiquant qu’elle contient un instant (created_at, updatedAt, signup_date, timestamp) est une date lorsque chaque valeur est un horodatage epoch entre 2001 et 2103, en secondes ou en millisecondes ; sous tout autre nom, ou avec toute autre valeur, elle reste un nombre.

Configuration de l’importation

L’importation est disponible sur chaque collection. Il n’existe aucun paramètre par collection permettant de la désactiver.

Exporter des données

Comment exporter

1. Ouvrez une collection dans le panneau d’administration
2. Appliquez éventuellement des filtres pour exporter un sous-ensemble de données
3. Cliquez sur le bouton Export dans la barre d’outils
4. Choisissez le format : CSV ou JSON
5. Le fichier se télécharge immédiatement

Formats d’exportation

Format	Description
CSV	Valeurs séparées par des virgules, compatible avec Excel et Google Sheets
JSON	Tableau d’objets, utile pour une utilisation programmatique

Filtrer avant l’exportation

Tous les filtres actifs dans la vue de la collection sont appliqués à l’exportation. Cela vous permet d’exporter uniquement un sous-ensemble de vos données :

• Appliquez des filtres de colonne ou des termes de recherche dans la vue de la collection
• Cliquez sur Export — seules les lignes filtrées seront incluses

Configuration de l’exportation

L’exportation est disponible sur chaque collection, sauf si vous la désactivez. admin.exportable permet de la configurer : exportable: false supprime le bouton Export, et un ExportConfig le conserve et ajoute des colonnes calculées, comme indiqué ci-dessous.

Ajouter des champs calculés

Utilisez l’objet ExportConfig pour ajouter des colonnes calculées personnalisées à vos exportations. Ces colonnes n’existent pas dans la base de données — elles sont calculées au moment de l’exportation :

import { defineCollection } from "@rebasepro/cms-types";

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: { /* ... */ },
    admin: {
        exportable: {
            additionalFields: [
                {
                    key: "computed_margin",
                    builder: ({ entity }) => {
                        const price = entity.values.price as number;
                        const cost = entity.values.cost as number;
                        return String(price - cost);
                    }
                },
                {
                    key: "full_url",
                    builder: ({ entity }) => {
                        return `https://mystore.com/products/${entity.id}`;
                    }
                }
            ]
        }
    }
});

Chaque entrée d’additionalFields comporte :

Propriété	Type	Description
key	string	Nom de la colonne dans l’exportation
builder	({ entity, context }) => string | Promise<string>	Fonction qui calcule la valeur

La fonction builder reçoit l’entity actuelle et le RebaseContext (qui inclut l’utilisateur authentifié), ce qui vous permet de calculer des valeurs en vous basant à la fois sur les données et sur les permissions.

Champs calculés asynchrones

La fonction builder peut être asynchrone, ce qui est pratique lorsque la valeur calculée nécessite une recherche dans la base de données ou un appel d’API :

exportable: {
    additionalFields: [
        {
            key: "author_name",
            builder: async ({ entity, context }) => {
                const author = await context.data.users.findById(
                    entity.values.authorId as string
                );
                return author?.values.displayName ?? "Unknown";
            }
        }
    ]
}

Prochaines étapes

• Collections — Définissez votre modèle de données
• Frontend Overview — Panneau d’administration et composants d’interface utilisateur
• SDK typé — Accès programmatique aux données