Ligne de commande

La plupart des opérations courantes s’effectuent en ligne de commande avec l’outil insitu.

Astuce

Tous les exemples supposent que la commande insitu est dans le chemin de votre shell, ce qui suppose généralement d’avoir activé l’environnement virtuel où elle a été installé.

Aide en ligne

L’outil dispose d’une aide en ligne intégrée. Si vous tapez l’une de ces commandes, il vous affichera le détail des sous-commandes et options disponibles :

insitu -h
insitu --help

De la même manière, il est possible d’obtenir de l’aide sur une sous-commande. Par exemple :

insitu import -h
insitu import --help

Jeux de données

Lister les jeux de données connus

Pour lister tous les jeux de données connus, avec leur dernière date d’importation :

 insitu datasets list

Pour lister uniquement les jeux de données qui n’ont pas encore été importés :

 insitu datasets list --missing

Pour lister uniquement les jeux de données distants (téléchargeables depuis une URL publique) :

 insitu datasets list --remote

Pour lister uniquement les jeux de données locaux (qui doivent être importés directement à partir d’un fichier privé) :

 insitu datasets list --local

Ajouter une définition pour un fichier local

C’est un prérequis pour apprendre à insitu comment importer le fichier.

Format Data Package

Pour produire une définition au format Data Package :

frictionless describe fichier.csv

Si le fichier est au format .xlsx et que vous voulez pointer vers un onglet spécifique :

frictionless describe --dialect ’{"excel": {"sheet": "la_feuille"}}’ Tableau.xlsx

Format insitu

Info

Le format historique d’insitu est susceptible d’être déprécié, et nous recommandons d’utiliser plutôt le format Data Package si possible.

Pour produire une définition dans le format historique d’insitu :

insitu sniff fichier.csv

Ajouter une définition pour une table Grist

Pour créer une définition YAML d’un jeu de données pour une table d’un document Grist, copiez l’URL de téléchargement CSV de cette table, puis utilisez la commande suivante (attention à ajouter des guillemets doubles autour de l’URL, pour que le shell n’interprète pas le caractère &) :

insitu datasets create-grist-definition "https://example.org/o/monorg/api/docs/XXXXXXXX/download/csv?viewSection=1&tableId=Table"

Vous pouvez spécifier le nom de la table PostgreSQL pour ce jeu de données en utilisant l’option --table-name :

insitu datasets create-grist-definition "https://example.org/o/monorg/api/docs/XXXXXXXX/download/csv?viewSection=1&tableId=Table" --table-name=foo

Indicateurs

Lister les indicateurs

Pour lister tous les indicateurs, groupés par espace de noms :

 insitu indicateurs liste

 insitu indicateurs liste --meta   # inclure les métadonnées

Afficher les valeurs des indicateurs

Pour afficher les valeurs calculées pour un indicateur pour à toutes les mailles :

 insitu indicateurs valeurs [--maille=commune|département|région|pays] <identifiant>

 insitu indicateurs valeurs --help

Pour afficher les valeurs calculées pour tous les indicateurs dans un territoire donné :

 insitu indicateurs territoire <commune|département|région|pays> <code_insee>

 insitu indicateurs territoire --help

Mettre à jour les vues SQL des indicateurs

Pour créer ou mettre à jour les vues SQL pour les indicateurs :

 insitu indicateurs synchroniser-vues

Tables de la base de données

Lister les tables de la base de données

Pour lister toutes les tables de données existantes dans la base :

 insitu tables

Lister les tables orphelines de la base de données

Pour lister les tables orphelines de la base de données (lorsque la définition du jeu de données associé a été supprimée) :

 insitu tables --list-orphans

Supprimer les tables orphelines de la base de données

Pour supprimer les tables orphelines de la base de données (lorsque la définition du jeu de données associé a été supprimée) :

 insitu tables --delete-orphans

Récupérer les jeux de données distants

Certains jeux de données ont une URL source à partir de laquelle ils peuvent être téléchargés.

Choisir les jeux de données à moissonner

Pour récupérer des jeux de données spécifiques :

insitu harvest toto tata

Pour tenter de récupérer les nouveaux jeux de données, ceux dont la date de mise à jour prévisionnelle a été atteinte, et ceux dont la périodicité de mise à jour est inconnue :

insitu harvest

Pour savoir quels jeux de données vont être moissonnés, sans lancer le téléchargement :

insitu harvest --list-only

Pour tenter de récupérer tous les jeux de données, même si leur date de mise à jour prévisionnelle n’a pas encore été atteinte :

insitu harvest --force

Import après téléchargement

L’action par défaut est de sauvegarder les fichiers téléchargés dans le répertoire courant.

Vous pouvez vouloir importer immédiatement le fichier téléchargé :

insitu harvest --action=import toto

Si vous ajoutez le flag --archive, les fichiers importés seront sauvegardés dans le répertoire config.ARCHIVEDIR, qui est ./tmp/archive par défaut :

insitu harvest foo --action=import --archive

Importer des fichiers

La commande insitu import vous permet d’importer le contenu d’un fichier local correspondant à une définition de jeu de données existante dans la base de données.

Sélectionner le(s) fichier(s) à importer

Pour importer un ou plusieurs fichiers spécifiques :

insitu import chemin/vers/fichier1.csv chemin/vers/fichier2.xlsx

Pour importer tous les fichiers d’un répertoire :

insitu import chemin/vers/repertoire

Importer tous les fichiers du répertoire par défaut

Pour importer tous les fichiers du répertoire config.WORKDIR (qui est ./tmp/inbox par défaut) :

insitu import

Options

--dataset

Vous pouvez spécifier explicitement le jeu de données à importer en donnant son nom de table (sinon insitu essaiera d’importer tous les jeux de données dont le modèle correspond au nom de fichier) :

insitu import fichier.csv --dataset=foo

--params

Dans ce cas, vous pourriez aussi avoir besoin d’ajouter manuellement des paramètres d’importation, qui auraient autrement été extraits du nom de fichier (en utilisant des groupes nommés dans l’expression régulière) :

insitu import fichier.csv --dataset=foo --params=’{"annee": "2023"}’

--sheetname

Vous pouvez spécifier le nom de la feuille à utiliser pour l’importation :

insitu import fichier.csv --sheetname=foo

--archive

Si vous ajoutez le flag --archive, les fichiers importés seront déplacés vers le répertoire config.ARCHIVEDIR, qui est ./tmp/archive par défaut :

insitu import fichier.csv --archive

--export

Si vous ajoutez le flag --export, les tables importées seront exportées vers le répertoire config.WRITEDIR, qui est ./tmp/out par défaut :

insitu import fichier.csv --export

--dry-run

Si vous ajoutez le flag --dry_run, le processus d’importation s’exécutera mais effectuera un rollback avant de valider les données dans la base de données. C’est utile pour tester si une importation produit les résultats attendus. Notez que cela désactivera les options --archive et --export.

insitu import fichier.csv --dry-run

--last-modified

Vous pouvez également spécifier la date de dernière modification du jeu de données si vous la connaissez :

insitu import fichier.csv --last-modified=2022-12-31

Exporter des jeux de données

Pour exporter tous les jeux de données qui ont changé depuis la dernière exportation :

insitu exsitu export

Pour exporter les tables associées à un jeu de données donné :

insitu exsitu export --name="France Mobile"

Pour forcer l’exportation de tous les jeux de données :

insitu exsitu export -f