Envision carga y procesa archivos tabulados que están almacenados en su cuenta de Lokad. Además, Lokad proporciona respaldo nativo para una serie de aplicaciones de terceros. Cuando su aplicación es compatible con Lokad, la importación de datos y la creación de los archivos necesarios es un proceso que nos encargamos de gestionar internamente en su totalidad. Sin embargo, cuando ese no es el caso, o cuando Lokad no logra recuperar todos los datos relevantes, es posible importar los archivos a Lokad en forma manual. Esta página detalla el modo en que deberían formatearse estos archivos tabulados para ser compatibles con Envision. Además, se documenta la sintaxis de Envision relativa al modo en que el sistema lee estos archivos tabulados.
Resumen
Estos son los formatos de archivo admitidos por Lokad:
- CSV, TSV y otros archivos de texto plano habituales similares, archivos
.csv, .tsv o .txt. - Archivos de Microsoft Excel 2007+, archivos
.xlsx. - Ficheros GZip, archivos
.gz; se espera que el contenido sea un archivo plano. - Ficheros WinZip, archivos
.zip; se espera que el contenido sea un archivo plano. El archivo debería contener exactamente 1 archivo. - Ficheros 7z, archivos
.7z; se espera que el contenido sea un archivo plano. El archivo debería contener exactamente 1 archivo.
La sintaxis para leer archivos en Envision es la siguiente:
read "/foo/myorders.csv.gz" as Orders with
"My Id" as Id
Quantity : number
// comodín '*' aquí
// se leerán varios archivos
read "/foo/promos*.xlsx" as Promos[*]
// máx. dentro del comodín '*'
// solo se lee un archivo
read max "/foo/stocks*.xlsx" as Stocks[*]
// 'no seguro' tolera problemas de análisis
read "/foo/backorders.tsv.zip" unsafe as BO[Date, *]
Almacenamiento de archivos con conectores
Todas las cuentas de Lokad incluyen su propio servicio de almacenamiento de archivos. En pocas palabras, es posibles crear carpetas y cargar archivos en esas carpetas. En este sentido, Lokad ofrece un servicio similar a otros servicios de hospedaje de archivos, como Box o Dropbox, excepto que no incluye la mayor parte de las funciones para compartir archivos. De hecho, el propósito del sistema de almacenamiento de archivos de Lokad no es ser una aplicación más para compartir archivos, sino proporcionar un modo completamente transparente de tener acceso a todos los datos utilizados por Lokad cada vez que se lleve a cabo un análisis de su comercio. Por lo tanto, cada vez que Lokad genera un pronóstico o un panel de información, los datos correspondientes existen dentro de su cuenta bajo la forma de archivos que pueden descargarse y, posiblemente, analizarse independientemente de Lokad.
Para empresas más pequeñas, la elaboración de archivos que reúnen todos los datos históricos de la empresa puede resultar un ejercicio bastante tedioso, porque tales empresas no siempre cuentan con recursos informáticos de envergadura. Por lo tanto, para muchas aplicaciones de comercio populares —Brightpearl, Linnworks, QuickBooks, TradeGecko, Unleashed, Vend, por nombrar algunas—, Lokad proporciona conectores integrados. Estos conectores pueden, valga la redundancia, conectarse a la aplicación, generalmente utilizando una API (interfaz de programación de aplicación) en línea, y generar dentro de una cuenta de Lokad archivos que se formatean directamente de un modo que los hace adecuados para que Envision los procese.
Si su aplicación de Lokad no es compatible (si es así
envíenos un correo, ya que en general ofrecemos compatibilidad con las aplicaciones que se solicitan con más frecuencia), o si el respaldo integrado de Lokad no cubre todos los datos relevantes, es posible cargar los archivos
directamente en Lokad, ya que respaldamos las cargas manuales a través de la web. Sin embargo, debido a que los datos deberán actualizarse con regularidad, resulta mucho más práctico si la transferencia de datos puede realizarse de un modo completamente automatizado. Por lo tanto, Lokad también respalda protocolos como FTP o SFTP, que ofrecen la posibilidad de automatizar todas las transferencias de archivos.
Respaldo extensivo para archivos tabulados
Lokad respalda una gama bastante amplia de formatos de archivos que pueden contener datos tabulados. Respaldamos formatos populares, como planillas de Excel o archivos CSV (valores separados por comas). Si tiene experiencia con la importación/exportación de archivos planos, tal vez ya sepa que existen infinidad de pequeños detalles técnicos que pueden hacer que el proceso resulte bastante tedioso:
- La codificación del archivo puede ser diferente de la codificación esperada por la aplicación.
- Las fechas o los números pueden no tener el formato esperado.
- La codificación del delimitador de columna o de la devolución de línea también pueden diferir.
Hemos diseñado nuestro sistema para que sea capaz de autodetectar todos los aspectos técnicos, como la codificación, los formatos de fechas y números, los delimitadores, etc. Si bien todo sucede automáticamente, es un proceso bastante complejo que tiene lugar dentro de Lokad cuando nuestro sistema lee los archivos. Por ejemplo, actualmente respaldamos la autodetección de más de 100 formatos de fecha distintos.
En la práctica, las directrices para el formato de archivo tabulado son simples: los nombres de las columnas deberían enumerarse como la primera línea del archivo (este requisito también se aplica en las planillas de Excel), y es preciso asegurarse de que los valores de token no entren en conflicto con los delimitadores al utilizar archivos de texto planos, como CSV o TSV.
Además, cuando los archivos aumentan en dimensión, podría resultar más práctico comprimirlos antes de cargarlos en Lokad. Lokad respalda archivos de texto planos comprimidos con GZip, siempre que se agregue la extensión
.gz al final del nombre del archivo. Por ejemplo,
Lokad_Items.tsv.gz se reconoce como un archivo TSV comprimido con GZip. El mismo patrón funciona con la extensión
.zip para ficheros WinZip, y con la extensión
.7z para ficheros 7z. En los casos de WinZip y 7z, los ficheros deberían contener un solo archivo comprimido, ya que Envision no admite ficheros multiarchivo. Las planillas de Excel ya están comprimidas, por lo que no es necesario comprimirlas, aunque sean muy grandes.
Directrices para la nomenclatura de archivos y columnas
Lokad puede incluir casi cualquier nombre de archivo y nombre de columna, pero si se siguen ciertas reglas, el script de Envision resultante puede simplificarse significativamente. El
conjunto de datos de ejemplo es un buen ejemplo de un conjunto de archivos que siguen estas directrices. Si aún no ha tenido la oportunidad de echarle un vistazo a este conjunto de datos, le sugerimos que lo haga ahora.
Se espera que la nomenclatura de los archivos siga este patrón: en
Lokad_TableName.xyz, el
TableName se reemplaza por el nombre de la tabla, y
xyz se reemplaza por la extensión real del archivo, por ejemplo
xlsx para planillas de Excel. El nombre de la tabla no debería contener espacios ni comenzar con un dígito. Siguiendo estas convenciones de nomenclatura, Envision es capaz de autodetectar las tablas relevantes para que se carguen en Lokad sin necesidad de realizar otras acciones.
En particular, la
tabla de artículos (
items) es un caso especial y, para muchos scripts de Envision, estructurar los datos alrededor de esa tabla de
artículos trae beneficios. Sin embargo, la tabla
artículos no es necesaria, y Envision puede funcionar sin cargarla. Si se le proporciona a Envision un archivo de nombre
Lokad_Items.xyz, este se procesará como la tabla
artículos por defecto.
Si una tabla resulta estar dividida en varios archivos, por ejemplo, porque los archivos individuales son demasiado grandes, entonces Envision puede consolidar todos esos archivos en una tabla. Para lograr esto, todos esos archivos deberían llamarse
Lokad_TableName_Suffix.xyz, donde el
Suffix varía entre un archivo y otro. Por ejemplo, si se elaboran extractos diarios para los extractos de ventas, uno de los extractos diarios probablemente se llame
Lokad_Orders_2015-03-16.tsv. La única función que desempeña el
Suffix es la de mantener diferenciados a los archivos, así que aquí puede escribirse cualquier cosa. Naturalmente, Envision espera encontrar las mismas columnas en todos los archivos, siendo la única variación sus sufijos; de lo contrario, Envision no podrá consolidar esos archivos en una tabla sin instrucciones adicionales.
Los nombres de columna vienen con pocas expectativas de parte de Envision. Envision también proporciona algunos comportamientos predeterminados:
- Cuando se encuentra una columna llamada
Id es un archivo simple, por defecto esta columna se trata como una clave externa para la columna Id que se encontraba originalmente en el archivo Lokad_Items.xyz. - Cuando una columna lleva un nombre que termina con
Date, Envision trata a esta columna por defecto como una fecha.
La mayoría de los nombres de columnas son aceptables siempre que no contengan espacios ni comiencen con un dígito. Envision también proporciona modos para invalidar los comportamientos enumerados anteriormente. Sin embargo, siempre que fuera posible, le sugerimos seguir las directrices, ya que esto reducirá la cantidad de tiempo adicional que deberá invertir en escribir scripts dentro de Envision para comenzar a obtener resultados.
Sintaxis para leer archivos
Envision admite una sintaxis rica para la lectura de archivos que puede gestionar situaciones en las que no es posible seguir nuestras directrices de nomenclatura (por ej., cuando los archivos no pueden modificarse internamente). La sintaxis se detalla a continuación. No se trata aún de la sintaxis general completa; se detallan a continuación algunas opciones adicionales.
read "/foo/bar*.xyz" as MyTable with
"Foo1" as Id
"Foo2" as Date
"Foo 3" as Foo3
La ruta
/foo/bar*.xyz puede contener un carácter comodín (*), y este puede reemplazarse por cualquier secuencia de caracteres. El uso de un carácter comodín es opcional, pero cuando se utiliza, ofrece la posibilidad de capturar varios archivos a la vez. Este patrón es similar al de la sintaxis de la shell cuando se enumeran archivos desde la línea de comando.
La primera palabra clave
as, que se encuentra apenas después de la ruta, indica el nombre de la tabla. Si la tabla se llama
MyTable, el script de Envision hará referencia a esta tabla escribiendo, por ejemplo,
MyTable.Id. Si la tabla que se debe cargar es la tabla artículos misma, entonces puede saltarse este
as MyTable.
Las instrucciones que vienen después bajo la forma de de la palabra clave
with actúan como instrucciones de re-nombramiento de columna. En el ejemplo anterior, la columna
Foo1 se vuelve a nombrar como
Id, y la columna
Foo2 se vuelve a nombrar como
Date. A través del re-nombramiento de estas dos columnas, la tabla
MyTable se convierte en una tabla legítima de Envision que contiene datos históricos, ya que tanto la columna
Id como la
Date ahora están definidas adecuadamente.
La tercera operación de re-nombramiento tiene lugar cuando
Foo 3 (note el espacio en el nombre de la columna original) se re-nombra como
Foo3. Esto ilustra el modo en que puede corregirse un nombre de columna incorrecto. También es importante notar que los nombres de variable de vector no permiten espacios. Para ser concisos, no hemos incluido más pares de re-nombramiento, pero, en realidad, siempre que los pares estén adecuadamente delimitados por comas, no hay un límite para la cantidad de operaciones de re-nombramiento que pueden realizarse para un solo archivo. En la práctica, el re-nombramiento puede resultar útil para hacer que el script resulte más legible, pero también puede utilizarse para hacer los ajustes oportunos cuando sea necesario consolidar varios archivos en una tabla y estos archivos tengan nombres de columnas no uniformes.
Por ejemplo, supongamos que el historial de pedidos está dividido en dos archivos. Primero, tenemos
Lokad_Orders_Old.tsv, que contiene todos los datos hasta el 31 de diciembre de 2014. Este archivo contiene tres columnas, llamadas
ItemId,
OrderDate y
Quantity respectivamente. Las columnas de este archivo no siguen las directrices de nomenclatura de columna de Envision. Luego, tenemos
Lokad_Orders.tsv, un archivo más reciente, que contiene todo el historial desde el 1 de enero de 2015. Este archivo también contiene tres columnas, y esas columnas se llaman
Id,
Date y
Quantity, lo cual coincide con las directrices predeterminadas de Envision. El script a continuación ilustra el modo en que los dos archivos pueden consolidarse en una sola tabla
Orders.
read "/foo/Lokad_Orders_Old.tsv" as Orders with
"ItemId" as “Id”
"OrderDate" as Date
read "/foo/Lokad_Orders.tsv" as Orders
Naturalmente, es posible definir tantas instrucciones
read como sea necesario para cubrir adecuadamente todos los archivos y todas las tablas. Envision no impone una ubicación precisa para estas instrucciones dentro de su script, así que, técnicamente, podrían ubicarse en cualquier parte, incluso al final del script. Sin embargo, le sugerimos que mantenga estas instrucciones al principio de los scripts, porque es allí donde la gente familiarizada con los lenguajes de programación se esperaría encontrarlas.
Filtros para comodines
El comodín (*) ofrece la posibilidad de seleccionar varios archivos. Sin embargo, a veces, el objetivo es leer un solo archivo de muchos. Si el objetivo es leer solo el
último archivo al ordenar los archivos de acuerdo con su nombre, esto puede hacerse con:
read max "/foo/bar*.xyz" as MyTable with
"Foo1" as Id
"Foo2" as Date
"Foo 3" as Foo3
Hay 3 filtros de comodín disponibles:
min: el primer archivo al ordenar los archivos de acuerdo con sus nombres (orden lexicográfico).min: el último archivo al ordenar los archivos de acuerdo con sus nombres (orden lexicográfico).latest: el último archivo al ordenar los archivo de acuerdo con la fecha de última modificación.
Por ejemplo, si se introduce una instantánea de niveles de stock en Lokad a diario con un archivo llamado
stocks-2016-12-21.csv, con el sufijo adaptado para indicar la fecha actual, lo más probable es que el objetivo sea leer solo el archivo más reciente. En este caso específico, tanto
max como
latest darían el mismo resultado, porque la convención de designación de un archivo es coherente con las fechas de actualización.
Definición de las expectativas de tipo
A menos que se especifique de otro modo, Envision se espera que cualquier tabla, con excepción de la tabla
Items, contenga tanto una columna
Id como una
Date, lo cual puede obtenerse a través del re-nombramiento de las columnas correspondientes, como se detallaba en la sección anterior. Sin embargo, a veces, una tabla puede no corresponder exactamente con estas expectativas, y la sintaxis de Envision puede utilizarse para clarificar cualquier expectativa asociada a una tabla. De modo similar, el tipo de columna generalmente se infiere del script de Envision mismo, pero, a veces, la deducción de tipo por sí sola no es suficiente. Una vez más, la sintaxis de Envision ofrece la posibilidad de especificar cualquier tipo de columna que pueda ser necesaria.
Envision ofrece la posibilidad de definir las claves primarias de una tabla poniéndolas en una lista entre corchetes inmediatamente después de la definición. Existen solo 7 combinaciones de claves primarias permitidas:
read "a.csv" as A[*]
read "b.csv" as B[Id]
read "c.csv" as C[Id, *]
read "d.csv" as D[Date]
read "e.csv" as E[Date, *]
read "f.csv" as F[Id, Date]
read "g.csv" as G[Id, Date, *]
El caso
A[*] define una tabla ningún tipo de restricción. Es un comodín y admite escenarios muy diversos, pero cuando no haya una columna
Id, se perderá algunas de las ventajas del lenguaje Envision.
El caso
B[Id] define una tabla con una línea por artículo como máximo. Por ejemplo nuestros
parámetros de inventario entran en esta categoría.
El caso
C[Id, *] define una tabla con una cantidad cualquiera de líneas por artículo. Por ejemplo, una tabla que represente una
distribución de probabilidades entraría en esta categoría.
El caso
D[Date] define una tabla que contiene un solo valor escalar para determinados días. Por ejemplo, una tabla de este tipo puede utilizarse para realizar una lista de los feriados nacionales aplicables a determinadas ubicaciones geográficas.
El caso
E[Date, *] define una tabla que contiene un número indeterminado de valores escalares para determinados días. Es una extensión del caso anterior, en el que un día determinado puede asociarse con múltiples factores.
El caso
F[Id, Date] define una tabla que contiene, como máximo, un valor para cada emparejamiento
[Id, Date]. Por ejemplo, una tabla de este tipo podría utilizarse para realizar una lista de las situaciones de desabastecimiento pasadas.
El caso
G[Id, Date, *] es el comportamiento por defecto, el que se obtiene cuando se omiten los corchetes. En la práctica, la mayoría de los datos históricos entran en este caso; por ejemplo, el historial de órdenes de ventas.
Restricciones de tipo en columnas de tabla
Envision en un lenguaje muy ligado a los tipos. Esto significa que todos los vectores se asocian a uno de los tipos disponibles en Envision, que son solo 4:
text,
number,
date y
boolean. Estos tipos generalmente se infieren directamente del script. Sin embargo, es posible especificar las expectativas de tipo con:
read "a.csv" as A[*] with "Foo" as X : text, Y : number, Z : date
Luego, volviendo al conjunto de datos de ejemplo, si escribimos:
// estas tres líneas son estándar
// y de ahora en adelante pueden omitirse
read "/sample/Lokad_Items.tsv"
read "/sample/Lokad_Orders.tsv" as Orders
read "/sample/Lokad_PurchaseOrders.tsv" as PO
Quantity = sum(Orders.Quantity)
Luego, el vector
Orders.Quantity se tipifica implícitamente como número, porque solo los números pueden sumarse. Como resultado, esto significa que cuando Envision analiza el archivo
Lokad_Orders.tsv, espera que la columna
Quantity contenga tokens que puedan analizarse correctamente como números. Si intentáramos escribir:
Nonsense = sum(Orders.Client)
En este caso, Envision intentaría analizar la columna
Client del archivo
Lokad_Orders.tsv con números, y el proceso fallaría, porque esta columna contiene identificadores de cliente que no son números.
Además del mecanismo de deducción de tipos, Envision también proporciona una sintaxis para especificar de modo explícito el tipo que se espera para cada columna de cada tabla. Por ejemplo, el conjunto de datos de ejemplo puede tipificarse explícitamente con las siguientes instrucciones:
expect Supplier : text
expect Orders.NetAmount : number
expect PO.ArrivalDate : date
La sintaxis incluye simplemente
expect MyTable.MyColumn : type, donde
type es uno de los cuatro tipos elegibles:
text,
number,
date o
boolean. La aserción de tipo más comúnmente utilizada es el tipo
date, porque, basándose solo en operaciones aritméticas y deducción de tipo, no siempre es posible deducir correctamente que se espera que una columna sea un fecha.
Opciones de análisis
El analizador de archivos de Envision es muy tolerante; no obstante, existen algunas situaciones en las que necesita un poco de ayuda. La opción
skip puede utilizarse para decirle al analizador que omita las N primeras líneas del archivo plano. La sintaxis es la siguiente:
read "/foo/bar*.csv" skip:2 as MyTable with "Foo1" as Id, "Foo2" as Date
En el ejemplo anterior, el analizador omite las primeras dos líneas del archivo plano y espera que los encabezados de la columna se encuentren en la tercera línea. La opción
skip es opcional, mientras que
skip:0 es el comportamiento predeterminado. Esta opción está pensada para gestionar sistemas que introducen metadatos al principio de las extracciones de sus archivos planos.
Lectura no segura
Por defecto, el analizador de archivo de Envision es estricto si se espera que un valor sea una fecha o un número, y si este valor no puede ser analizado correctamente como tal, la instrucción
read fallará y dará error. Como regla general, cuando Envision encuentra errores de análisis, la mejor opción es investigar
por qué el archivo está dañado. De hecho, dado que Envision es capaz de reconocer muchos formatos de fechas y números, es muy probable que, si Envision falla, el motivo sea que los datos estén dañados. Los archivos dañados pueden generar toda clase de errores. Cuando Envision falla, la mayoría de las veces se trata de un signo de un problema anterior.
Sin embargo, con conjuntos de datos grandes, los daños menores en archivos se vuelven mucho más difíciles de evitar. En particular modo cuando los datos dañados son, además, viejos. En esos casos, tal vez ni siquiera valga la pena corregirlos. Como consecuencia, para estas situaciones específicas, Envision admite un modo de lectura
unsafe, como se ilustra en la sintaxis a continuación:
read unsafe "/foo/orders.tsv" with
"My Id" as Id
"My Date" as Date
Cuando se utiliza el modo
unsafe, Envision trata los problemas de análisis como
advertencias en lugar de
errores. Esta opción permite que los cálculos continúen incluso cuando haya valores o líneas que hayan sido descartadas por el analizador porque no pudieron leerse.
