Lire des fichiers tabulaires avec Envision

Lire des fichiers tabulaires avec Envision










Accueil » Ressources » Ici

Envision charge et traite des fichiers tabulaires qui sont stockés sur votre compte Lokad. De plus, Lokad est compatible avec un certain nombre d’applications tierces. Lorsque c'est le cas pour votre application, l’importation de données et la création des fichiers requis sont entièrement gérées par notre équipe. Mais, si ce n’est pas le cas, si Lokad ne peut récupérer toutes les données nécessaires, il est possible d’importer des fichiers manuellement sur la plateforme Lokad. Cet article détaille le format que doivent avoir ces fichiers tabulaires pour être lus par Envision ainsi que la syntaxe des commandes de lectures.


En bref

Les formats de fichiers pris en charge par Lokad sont :

  • CSV, TSV et autres fichiers de texte plats, .csv, .tsv ou .txt.
  • Fichiers Microsoft Excel 2007 ou version supérieure, fichiers .xlsx.
  • Archives GZip, fichiers .gz ; le contenu doit être un fichier plat.
  • Archives WinZip, fichiers .zip ; le contenu doit être un fichier plat ; doit contenir exactement un fichier.
  • Archives 7z, fichiers .7z ; le contenu doit être un fichier plat ; doit contenir exactement un fichier.

La syntaxe de lecture de fichiers dans Envision est :
read "/foo/myorders.csv.gz" as Orders with "My Id" as Id, Quantity : number
read "/foo/promos*.xlsx" as Promos[*] // caractère générique '*', plusieurs fichiers seront lus
read max "/foo/stocks*.xlsx" as Stocks[*] // max au sein du caractère générique '*', un seul fichier est lu
read "/foo/backorders.tsv.zip" unsafe as Backorders[Date, *] // 'risqué' permet de tolérer des dates illisibles

Stockage de fichiers et connecteurs

Chaque compte Lokad dispose de son propre service de stockage de fichiers dans lequel il est possible de créer des dossiers et d’y télécharger des fichiers. À cet égard, Lokad offre un service similaire à d’autres services d’hébergement de fichiers comme Box ou Dropbox, sauf que la plupart des fonctionnalités classiques de ce type de service sont absentes. En fait, le but de Lokad n’est pas de faire concurrence aux applications d’hébergement mais d’offrir un accès transparent aux données utilisées par Lokad dès lors que l’activité de votre entreprise est analysée. Donc, dès que des prévisions ou qu’un tableau de bord est généré par Lokad, les données correspondantes sont disponibles dans votre compte Lokad, sous forme de fichiers téléchargeables et éventuellement analysables en dehors de Lokad.

Pour les petites entreprises, il peut être fastidieux de produire les fichiers qui regroupent toutes les données historiques nécessaires, parce que de telles entreprises n’ont pas toujours d’importantes ressources informatiques. Donc, Lokad offre un connecteur intégré vers de nombreuses applications de gestion commerciale populaires — Brightpearl, Linnworks, QuickBooks, TradeGecko, Unleashed, Vend… pour n’en nommer que quelques-unes. Ces connecteurs permettent à Lokad de se connecter à votre application, en général en utilisant une API (interface de programmation) en ligne, et de générer les fichiers, qui sont stockés sur votre compte directement au bon format et prêts à être utilisés par Envision.

Si votre application métier n’est pas compatible ( car Lokad est compatible avec les applications les plus demandées) ou si le connecteur intégré à Lokad n’est pas en mesure de rassembler toutes les données nécessaires, il est possible de télécharger des fichiers directement dans Lokad, qui peut recevoir des téléchargements manuels. Mais comme les données devront être mises à jour régulièrement, il est bien plus pratique que le transfert de données ait lieu automatiquement. Lokad est donc également compatible avec des protocoles tels que FTP et SFTP, qui offrent la possibilité d’automatiser tous les transferts de fichiers.

Fichiers tabulaires supportés

Lokad est capable de traiter une large gamme de formats de fichiers qui peuvent contenir des données tabulaires, notamment les feuilles de calcul Excel ou les fichiers CSV (comma-separated value). Si vous connaissez l’import/export de fichiers plats, vous savez qu’il y a de nombreux petits détails techniques qui peuvent rendre l’opération fastidieuse :

  • L’encodage du fichier peut être différent de celui attendu par l’application.
  • Les dates et numéros peuvent ne pas être au format attendu.
  • Les délimiteurs de colonne ou les retours à la ligne peuvent également être encodés différemment.

Nous avons conçu notre système pour que ce dernier soit capable de détecter automatiquement les détails techniques comme l’encodage, les formats de date et de numéro, les délimiteurs… Et, même si tout se passe automatiquement, c’est un processus relativement complexe qui se déroule dans Lokad lorsque notre système lit des fichiers. Plus de 100 formats de date différents peuvent notamment être détectés automatiquement.

Dans la pratique, les recommandations relatives au format d’un fichier sont simples : le nom des colonnes doit être indiqué dans la première ligne du fichier (tout comme pour les fichiers Excel) et il faut faire en sorte que les valeurs ne rentrent pas en conflit avec les délimiteurs dans les fichiers plats de type texte tels que les fichiers CSV ou TSV.

De plus, pour les fichiers de grande taille, il est plus pratique de les compresser avant de les télécharger sur Lokad, qui peut prendre en compte des fichiers compressés avec GZip si l’extension .gz est ajoutée à la fin du nom du fichier. Par exemple, Lokad_Items.tsv.gz est reconnu comme un fichier TSV compressé avec GZip. Le même principe s'applique à l'extension .zip des archives WinZip et l'extension .7z des archives 7z. Dans ces deux cas, les archives ne doivent contenir qu'un seul fichier compressé ; Envision ne prend pas en charge les archives à plusieurs fichiers. Les feuilles Excel sont déjà compressées, il n’est donc pas nécessaire de les compresser même si ce sont de gros fichiers.

Recommandations de nommage des fichiers et des colonnes

Lokad peut prendre en charge à peu près tous les noms de fichier et de colonne mais, en suivant certaines recommandations, le script Envision peut être simplifié. L'échantillon de données est un bon exemple d’un ensemble de fichiers qui suivent ces recommandations. Si vous n’avez pas encore jeté un œil à cet échantillon, nous vous suggérons de le faire maintenant.

Les fichiers doivent être nommés en suivant ce modèle : Lokad_TableName.xyz, en remplaçant TableName par le nom de la table et xyz par l’extension du fichier, par exemple xlsx pour les fichiers Excel. Le nom des tables ne doit pas contenir d’espace et ne doit pas commencer par un chiffre. En suivant ces conventions de nommage, Envision peut détecter automatiquement les tables à charger dans Lokad, sans effort supplémentaire.

La table des articles (items) est un cas particulier et, pour de nombreux scripts Envision, il est avantageux de structurer vos données autour d'une telle table. Elle n'est cependant pas obligatoire et Envision peut tourner sans. Si un fichier nommé Lokad_Items.xyz est fourni à Envision, il est traité par défaut comme la table des articles.

Si une table est répartie sur plusieurs fichiers, par exemple si un seul fichier est trop gros, Envision peut consolider ces fichiers en une table. Pour cela, tous ces fichiers doivent être nommés Lokad_TableName_Suffix.xyz, Suffix étant différent pour chaque fichier. Par exemple, si des extraits quotidiens sont produits pour les ventes, alors un de ces extraits peut être nommé Lokad_Orders_2015-03-16.tsv. Suffix ne joue aucun rôle à part celui de différencier les fichiers, donc n’importe quelle valeur peut être utilisée. Naturellement, tous les fichiers différenciés seulement par un suffixe doivent contenir les mêmes colonnes, sinon les données ne peuvent être consolidées par Envision dans une seule table sans instruction supplémentaire.

Envision fournit également des fonctionnements par défaut :
  • Lorsqu'une colonne dont le nom est Id est rencontrée dans un fichier plat, cette colonne est traitée, par défaut, comme une clé étrangère vers la colonne Id d'origine du fichier Lokad_Items.xyz.
  • Lorsque le nom d'une colonne se termine par Date, cette colonne est traitée par défaut comme une « Date » par Envision.

Le nom des autres colonnes ne doit pas contenir d’espace et ni commencer par un chiffre.

Envision fournit également des moyens de passer outre les fonctionnements cités ci-dessus. Cependant, autant que faire se peut, nous vous suggérons de suivre nos recommandations afin de réduire la taille du script nécessaire dans Envision pour obtenir les premiers résultats.

Syntaxe de lecture des fichiers

Envision offre une syntaxe de lecture de fichiers relativement riche. Celle-ci permet de gérer des situations dans lesquelles nos recommandations de nommage ne peuvent être suivies (c'est à dire lorsque les fichiers ne peuvent être modifiés en interne).

La syntaxe est la suivante, ce n'est pas encore la syntaxe générale complète, d'autres options sont détaillées plus loin :
read "/foo/bar*. xyz" as MyTable with "Foo1" as Id, "Foo2" as Date, "Foo 3" as Foo3
Le chemin /foo/bar*. xyz peut contenir le caractère générique (*), qui sera remplacé par n’importe quelle suite de caractères. L’utilisation d’un caractère générique est optionnelle mais offre la possibilité d’englober plusieurs fichiers en une fois. Ce modèle est similaire à la syntaxe Shell utilisée pour lister des fichiers avec une ligne de commande. Le premier mot-clé as, juste après le chemin, indique le nom de la table. Si cette dernière est nommée MyTable, alors le script Envision y fera référence en écrivant MyTable.Id par exemple. Si la table à charger est la table des articles elle-même, avec as MyTable n'est pas utile.

L'instruction suivante, après le mot-clé with fonctionne comme une instruction de renommage de colonne. Dans l'exemple ci-dessus, la colonne Foo1 est renommée Id et Foo2 est renommée Date. En renommant ces deux colonnes, la table MyTable devient une table Envision légitime qui contient des données historiques puisque les deux colonnes Id et Date sont correctement définies.

La troisième opération de renommage consiste à renommer Foo 3 (avec un espace dans le nom) en Foo3, ce qui illustre comment un nom de colonne incorrecte peut être corrigé. Il est important de noter également que le nom des variables vecteur ne peut contenir d'espace. Pour plus de concision, nous n'avons pas inclut plus d'exemples de renommage, mais tant que les renommages sont délimités correctement par des virgules, il n'y pas de limite à leur nombre pour chaque fichier. Il peut être pratique de renommer une colonne pour que votre script soit plus facile à lire. Cela peut être également nécessaire lors que vous consolidez plusieurs fichiers en une seule table mais que les noms de colonne de sont pas cohérents.

Prenons l'exemple d'un historique des commandes réparti sur deux fichiers. Tout d'abord, le fichier Lokad_Orders_Old.tsv contient les données jusqu'au 31 décembre 2014 sur 3 colonnes : ItemId, OrderDate et Quantity. Les colonnes de ce fichier ne suivent pas les recommandations de nommage d'Envision. Ensuite, le fichier Lokad_Orders.tsv, plus récent, contient l'historique depuis le 1er janvier 2015. Il contient aussi trois colonnes, qui sont nommées Id, Date et Quantity et suivent donc les recommandations Envision. Le script ci-dessous montre comment consolider les deux fichiers en une seule table Orders.
read "/foo/Lokad_Orders_Old.tsv" as Orders with "ItemId" as "Id", "OrderDate" as Date
read "/foo/Lokad_Orders.tsv" as Orders
Naturellement, il est possible de définir autant d'instructions read que nécessaire pour couvrir tous fichiers et toutes les tables. Ces instructions ne doivent pas se trouver à un endroit précis dans votre script, elles peuvent être placées n'importe où, même tout à la fin. Mais nous vous recommandons de les placer au début du script car c'est là où les utilisateurs qui connaissent les langages de programmation les chercheraient.

Filtres utilisant un caractère générique

Le caractère générique (*) offre la possibilité de sélectionner plusieurs fichiers. Pourtant, un seul fichier doit parfois être lu parmi plusieurs. Le code suivant permet de lire seulement le dernier fichier d'un ensemble de fichiers classés par leur nom :
read max "/foo/bar*.xyz" as MyTable with "Foo1" as Id, "Foo2" as Date, "Foo 3" as Foo3

Trois filtres utilisant un caractère générique sont disponibles :

  • min : premier des fichiers classés par nom (ordre lexicographique).
  • max : dernier des fichiers classés par nom (ordre lexicographique).
  • latest : dernier des fichiers classés par date de dernière modification.

Par exemple, si Lokad reçoit quotidiennement des informations sur les niveaux de stock dans un fichier nommé stocks-2016-12-21.csv (le suffixe correspondant à la date du jour), c'est probablement uniquement le dernier fichier qui doit être consulté. Dans ce cas, max et latest aboutissent au même résultat car la convention de nommage des fichiers est cohérente avec les dates de mise à jour.

Définir les types attendus

Sauf indication contraire, pour Envision, toutes les tables — sauf la table des articles (Items — doivent contenir une colonne Id et une colonne Date, qui peuvent être obtenues grâce au renommage. Cependant, il est possible qu'une table ne corresponde pas à ces attentes et la syntaxe Envision peut être utilisée pour clarifier toute attente associée à une table. De la même façon, le type de la colonne est déduit du script lui-même, mais ce n'est pas toujours suffisant. Là encore, la syntaxe Envision offre la possibilité de spécifier tous les types de colonne nécessaires.

Envision offre la possibilité de définir les clés primaires d'une table, en les listant entre parenthèses juste après la définition. Seules sept combinaisons de clés primaires possibles :
expect A[*]
expect B[Id]
expect C[Id, *]
expect D[Date]
expect E[Date,*]
expect F[Id, Date]
expect G[Id, Date,*]
Le cas A[*] définit un table sans aucune contrainte. Il s'agit d'une table générique qui convient à divers scénarios mais, sans colonne Id, vous passez à côté des subtilités du langage Envision.

Le cas B[Id] définit une table avec une ligne par article, au plus. Par exemple, nos paramètres de stock rentrent dans cette catégorie.

Le cas C[Id, *] correspond à une table avec un nombre indéterminé de lignes par article. Par exemple, une table qui représente une distribution des probabilités appartient à cette catégorie.

Le cas D[Date] définit une table qui contient une seule valeur scalaire pour certains jours. Une telle table peut être utilisée, par exemple, pour établir la liste des jours fériés dans certaines régions du monde.

Le cas E[Date, *] définit une table qui contient un nombre indéterminé de valeurs scalaires pour certains jours. C'est une extension du cas précédent, dans laquelle un jour donné peut être associé à plusieurs facteurs.

Le cas F[Id, Date] correspond à une table qui contient au plus une valeur pour chaque paire [Id, Date], la liste des ruptures de stock passées par exemple.

Le cas G[Id, Date, *] correspond au fonctionnement par défaut, obtenu sans parenthèses. Dans la pratique, la plupart des données historiques rentrent dans cette catégorie, comme l'historique des commandes clients par exemple.

Contraintes sur les colonnes

De plus, Envision est un langage fortement typé, ce qui veut dire que tous les vecteurs sont associés à un type de données disponible dans Envision. Il n'y a que 4 types disponibles dans Envision : texte, nombre, date et booléen et ces types sont généralement déduits du script lui-même. Il est cependant possible de spécifier le type attendu avec :
read "a.csv" as A[*] with "Foo" as X : text, Y : number, Z : date
Mais revenons à l'exemple, si nous écrivons :
read "/sampleLokad_Items.tsv"
read "/sample/Lokad_Orders.tsv" as Orders
read "/sample/Lokad_PurchaseOrders.tsv" as PO
// les trois lignes ci-dessus seront omises dans la suite
Quantity = sum(Orders.Quantity)
Alors le vecteur Orders.Quantity reçoit implicitement le type nombre car seuls des nombres peuvent être ajoutés. Par conséquent, lorsqu'Envision parse le fichier Lokad_Orders.tsv, la colonne Quantity doit contenir des valeurs qui peuvent recevoir le type nombre. Si nous écrivions :
Nonsense = sum(Orders.Client)
Dans ce cas, Envision essaierait de parser la colonne Client du fichier Lokad_Orders.tsv avec des nombres et échouerait, parce que cette colonne contient des identifiants de clients qui ne sont pas des nombres. En plus du mécanisme de déduction des types, Envision dispose d'une syntaxe qui permet de spécifier le type des données de chaque colonne de chaque table. Par exemple, il est possible de spécifier des types pour les données de l'échantillon avec les instructions suivantes :
expect Supplier : text
expect Orders.NetAmount : number
expect PO.ArrivalDate : date
La syntaxe fonctionne ainsi expect MyTable.MyColumn : type et type doit être un des quatre types disponibles (text, number, date ou boolean). C'est le type date qui est le plus souvent défini explicitement, car il n'est pas toujours possible de déduire qu'une colonne contient des dates simplement à partir des opérations arithmétiques ou du code.

Options d'analyse des fichiers

Le parseur de fichiers Envision est très souple mais, dans certains cas, un peu d'aide est nécessaire. L'option skip permet de demander au parseur d'ignorer les N premières lignes d'un fichier plat. Voici la syntaxe :
read "/foo/bar*.csv" skip:2 as MyTable with "Foo1" as Id, "Foo2" as Date
Dans cet exemple, le parseur ignore les deux premières lignes du fichier plat et s'attend à trouver les en-têtes des colonnes à la troisième ligne. L'option skip est facultative et skip:0 est le comportement par défaut. Cette option est conçue pour adapter les scripts aux systèmes qui incluent des méta-données au début de leurs extractions de fichiers plats.

Lecture risquée

Par défaut, le parseur de fichier Envision est stricte : si une valeur doit être une date ou un nombre, et si cette valeur ne peut être parsée en tant que telle, l'instruction read échoue et renvoie une erreur. D'une manière générale, lorsqu'Envision rencontre des erreurs de parseur, la meilleure option consiste à « déterminer pourquoi le ficher est corrompu ». En effet, puisqu'Envision est capable de reconnaître de nombreux formats de dates et de nombres, il y a des chances pour que les données soient corrompues si Envision échoue à les lire. Des données corrompues peuvent entraîner toutes sortes d'erreurs. L'échec d'Envision n'est qu'un signe visible d'un problème qui a eu lieu en amont.

Cependant, lorsque le volume des données est important, la présence de données corrompues de façon mineure est inévitable. Leur correction ne vaut pas la peine, en particulier lorsque les données corrompues sont anciennes. Ainsi, dans ces cas-là, Envision propose le mode de lecture unsafe, comme l'illustre la syntaxe ci-dessous :
read "/foo/orders.tsv" unsafe with "My Id" as Id, "My Date" as Date
Lorsqu'unsafe est utilisé, les problèmes de parseur sont traités comme des avertissements et non comme des erreurs. Cette option laisse le calcul se dérouler même si des valeurs ou des lignes ont été écartées par le parseur parce qu'illisibles.