Чтение табличных файлов


Главная » Ресурсы » Здесь

Envision загружает и обрабатывает табличные файлы, которые хранятся в вашей учетной записи Lokad. Кроме того, Lokad поддерживает некоторые сторонние приложения. Если ваше приложение поддерживается Lokad, процесс импорта данных и создания необходимых файлов выполняется нами от начала до конца. Тем не менее, если приложение не поддерживается или Lokad не может получить все необходимые данные, можно импортировать файлы в Lokad вручную. На данной странице вы найдете подробную информацию о том, как нужно отформатировать табличные файлы, чтобы система Envision могла работать с ними. Синтаксис Envision, связанный с прочтением этих файлов системой, также описан ниже.


Краткое описание

Lokad поддерживает следующие форматы файлов:

  • CSV , TSV и другие простые текстовые файлы, файлы .csv и .tsv или .txt
  • Файлы Microsoft Excel версии 2007 и выше, файлы .xlsx.
  • Архивы GZip, файлы .gz; в них должны содержаться простые файлы.
  • Архивы WinZip , файлы .zip; в них должны содержаться простые файлы, в каждом архиве — по одному файлу.
  • Архивы 7z, файлы .7z; в них должны содержаться простые файлы, в каждом архиве — по одному файлу.

Синтаксис для считывания файлов в Envision:
read "/foo/myorders.csv.gz" as Orders with
  "My Id" as Id
  Quantity : number

// подстановочный знак «*» должен быть здесь
// будет прочитано несколько файлов
read "/foo/promos*.xlsx" as Promos[*]

// макс. в пределах подстановочного знака «*»
// прочитывается только один файл
read max "/foo/stocks*.xlsx" as Stocks[*]

// «опасное» игнорирование проблем с прочтением сценария
read "/foo/backorders.tsv.zip" unsafe as BO[Date, *]

Хранилище файлов и подключение к сторонним приложениям

Все учетные записи Lokad имеют собственную службу хранения файлов . Проще говоря, можно создавать папки и загружать файлы в эти папки. С этой точки зрения, Lokad предлагает услуги, подобные другим сервисам хранения данных, таким как Box или Dropbox, только в Lokad нет функции обмена файлами. Хранилище файлов Lokad задумывалось не как еще одно приложение для обмена файлами, а как средство получения доступа ко всем данным, используемым Lokad при анализе вашей коммерческой деятельности. Таким образом, каждый раз, когда Lokad создает прогнозы или панель управления, соответствующие данные хранятся в вашей учетной записи в виде файлов, которые можно загрузить и, возможно, проанализировать независимо от системы Lokad.

Создание файлов, которые содержат все необходимые исторические данные по компании, может отнимать очень много времени и сил, особенно у малых компаний, потому что они не всегда имеют доступ к мощным информационным ресурсам. Lokad поддерживает совместную работу со многими популярными коммерческими приложениями: Brightpearl, Linnworks, QuickBooks, TradeGecko, Unleashed, Vend и т. д. Благодаря этому система может подключаться к приложению, обычно с помощью API (программного интерфейса приложения), и создавать файлы в учетной записи Lokad, которые форматируются особым образом для обработки в Envision.

Если ваше приложение не поддерживается (в этом случае , так как мы стараемся обеспечивать поддержку самых популярных приложений) или Lokad не может получить все необходимые данные, можно загрузить файлы непосредственно в Lokad вручную через Интернет. Однако данные необходимо регулярно обновлять, поэтому очень желательно, чтобы передача данных происходила полностью автоматически. Поэтому Lokad также поддерживает протоколы типа FTP и SFTP для обеспечения автоматической передачи всех файлов.

Расширенная поддержка для табличных файлов

Lokad поддерживает довольно широкий набор форматов файлов, которые могут содержать таблицы . Мы поддерживаем популярные форматы, такие как Excel и CSV (файлы данных с разделителями-запятыми). Если вы уже пробовали импортировать/экспортировать простые файлы, то знаете, что существует огромное множество мелких технических нюансов, которые могут сделать этот процесс довольно трудоемким:

  • Кодировка файла может отличаться от кодировки, требуемой приложением.
  • Даты или числа могут иметь неверный формат.
  • Кодировка разделителя столбцов или строк также может отличаться от требуемой.

Наша система может автоматически обнаруживать все технические нюансы, такие как кодировка, формат дат и чисел, разделители и т. д. Все процессы выполняются автоматически, поэтому процесс чтения файлов системой Lokad не доставляет каких-либо трудностей. Например, на данный момент мы поддерживаем автоматическое обнаружение более 100 различных форматов даты.

На практике требования к формату табличных данных очень просты: имена столбцов должны быть перечислены в первой строке файла (данное требование распространяется в том числе и на файлы Excel), и нужно следить за тем, чтобы значения маркеров не конфликтовали с разделителями при работе с простыми текстовыми файлами, такими как CSV или TSV.

Кроме того, при работе с большими текстовыми файлами рационально сжимать их перед загрузкой в Lokad. Lokad поддерживает простые текстовые файлы, сжатые с помощью GZip, если в конце имени файла указано расширение .gz. Например, Lokad_Items.tsv.gz распознается как файл в формате TSV, сжатый с помощью GZip. Та же самая схема используется для расширения .zip архивов WinZip, и .7z для архивов 7z. Архивы WinZip и 7z должны содержать только по одному сжатому файлу. Envision не поддерживает работу с архивами, в которых находится несколько файлов. Таблицы Excel сжимаются по умолчанию, поэтому сжимать их дополнительно не требуется, даже если они очень большие.

Указания по присваиванию имен файлов и столбцов

Lokad может работать практически с любыми именами файлов и столбцов, но при соблюдении определенных требований создавать сценарии Envision будет гораздо проще. Образец набора данных — это хороший пример комплекса файлов, соответствующих этим требованиям. Если вы еще не ознакомились с этим набором данных, рекомендуем сделать это прямо сейчас.

Файлы следует называть следующим образом: в Lokad_TableName.xyzTableName меняется на имя таблицы, а xyz — на фактическое расширение файла, например xlsx для Excel. В имени таблицы не должно быть пробелов, и оно не должно начинаться с цифры. При выполнении этих требований к именам файлов Envision сможет автоматически находить и загружать нужные таблицы в Lokad без дополнительных действий.

В частности, особым случаем является таблица наименований, и многие сценарии Envision выигрывают от представления данных через таблицу наименований. Тем не менее таблица наименований (items) не является обязательной, и Envision может работать, не загружая ее. Если в Envision загружается файл с именем Lokad_Items.xyz, он будет по умолчанию считаться таблицей наименований.

Если таблица разбивается на несколько файлов, например из-за того, что исходный файл слишком велик, Envision может собрать все эти файлы в одну таблицу. Для этого все файлы должны иметь следующее имя: Lokad_TableName_Suffix.xyz, где Suffix различается в зависимости от файла. Например, если ежедневно создаются файлы, содержащие данные о продажах, то один из таких файлов может быть назван следующим образом: Lokad_Orders_2015-03-16.tsv. Suffix не играет какой-либо особенной роли: он нужен только для различения файлов, поэтому может содержать любую информацию. Естественно, для Envision желательно, чтобы во всех файлах, различающихся только суффиксом, были одни и те же столбцы, иначе Envision не сможет объединить эти файлы в одну таблицу без дополнительных инструкций.

С точки зрения Envision, имена столбцов имеют небольшое значение. Кроме того, Envision выполняет некоторые действия по умолчанию:
  • Если в простом файле есть столбец с именем Id, то он по умолчанию считается внешним ключом для столбца Id из файла Lokad_Items.xyz.
  • Если имя столбца оканчивается на Date, то он по умолчанию считается столбцом с датами в Envision.

Допустимы практически любые имена столбцов, если они не содержат пробелов и не начинаются с цифры. В Envision можно отменить действия по умолчанию, описанные выше. Тем не менее мы рекомендуем всегда придерживаться требований, так как это позволяет сократить код, который необходимо ввести, чтобы система Envision начала давать результаты.

Синтаксис для чтения файлов

Система Envision поддерживает синтаксис считывания файлов для таких случаев, когда выполнить наши требования к наименованию невозможно (например, когда файлы нельзя изменить). Синтаксис показан ниже. Это еще не полный стандартный синтаксис, дополнительные сегменты описываются ниже.
read "/foo/bar*.xyz" as MyTable with
  "Foo1" as Id
  "Foo2" as Date
  "Foo 3" as Foo3
Путь /foo/bar*.xyz может содержать подстановочный знак (*), и его можно заменить на любую последовательность символов. Использование подстановочного знака необязательно, но при использовании он позволяет работать с несколькими файлами сразу. Данная структура напоминает синтаксис оболочки при составлении списка файлов из командной строки.

Первое ключевое слово as, которое находится сразу же после пути, указывает на имя таблицы. Если таблица называется MyTable, то в сценарии Envision эта таблица будет записана, к примеру, как MyTable.Id. Если загружаемая таблица является таблицей наименований, то выражение as MyTable может быть пропущено.

Инструкции, заданные после ключевого слова with, работают как инструкции для переименования столбцов. В примере, приведенном выше, имя столбца Foo1 изменено на Id, а Foo2 — на Date. Благодаря переименованию этих двух столбцов таблица MyTable становится нормальной таблицей Envision, содержащей исторические данные, так как столбцы Id и Date теперь определены.

Третья операция переименования происходит из-за того, что имя Foo 3 (обратите внимание на пробел в исходном имени столбца) превращается в Foo3. Данный пример показывает, как неправильные имена столбцов могут быть превращены в правильные. Также важно заметить, что в именах векторных переменных использование пробелов также не допускается. Для краткости мы больше не стали включать пары изменяемых имен, но если эти пары правильно разделены запятой, количество операций переименования в одном файле не ограничено. На практике переименование столбца может быть полезно для упрощения чтения сценария, и эта функция также может быть использована для внесения необходимых изменений при слиянии нескольких файлов в одну таблицу, если имена столбцов в этих файлах невозможно сопоставить.

Например, предположим, что история заказов разбита на два файла. Первый файл, Lokad_Orders_Old.tsv, содержит все данные до 31 декабря 2014 года. Файл имеет три столбца с именами ItemId, OrderDate и Quantity соответственно. Имена этих столбцов в этом файле не соответствуют требованиям Envision Второй файл, Lokad_Orders.tsv, более новый, содержит все данные начиная с 1 января 2015 года. Данный файл также имеет три столбца: Id, Date и Quantity, соответствующие требованиям Envision. В сценарии ниже показано, как можно объединить эти два файла в единую таблицу Orders.
read "/foo/Lokad_Orders_Old.tsv" as Orders with
  "ItemId" as "Id"
  "OrderDate" as Date

read "/foo/Lokad_Orders.tsv" as Orders
Можно задавать столько операторов read, сколько необходимо для надлежащей работы со всеми файлами и всеми таблицами. Envision не предписывает точное расположение этих операторов в сценарии, поэтому технически их можно разместить где угодно, даже в самом конце сценария. Тем не менее мы рекомендуем располагать эти операторы в начале сценария, потому что именно там их будут искать пользователи, знакомые с программированием.

Фильтры с подстановочными знаками

Подстановочный знак (*) позволяет выбрать несколько файлов. Однако иногда он используется для считывания лишь одного файла из нескольких. Если нужно считать только "последний" файл, когда файлы сортируются по имени, то нужный синтаксис выглядит так:
read max "/foo/bar*.xyz" as MyTable with
  "Foo1" as Id
  "Foo2" as Date
  "Foo 3" as Foo3

Всего доступно 3 фильтра с подстановочными знаками:

  • min: первый файл при сортировке файлов по именам (лексикографическое упорядочение).
  • max: последний файл при сортировке файлов по именам (лексикографическое упорядочение).
  • latest: последний файл при сортировке файлов по дате последнего изменения.

Например, если данные об уровне запасов передаются в Lokad ежедневно в виде файла с именем stocks-2016-12-21.csv, последняя часть которого показывает текущую дату, то использование фильтра позволит прочитать только последний файл. В данном случае использование и max, и latest дает один и тот же результат, потому что при сортировке по имени и по дате обновления файл будет расположен на одной и той же позиции.

Определение ожидаемых типов

Помимо отдельно оговоренных случаев, все таблицы, кроме таблицы наименований Items в Envision, должны содержать столбцы Id и Date, которые можно получить путем переименования соответствующих столбцов, как говорилось в предыдущем разделе. Тем не менее иногда таблицы не совпадают с такими ожиданиями, и синтаксис Envision используется для прояснения ожиданий, привязанных к таблице. Точно так же тип столбца обычно определяется непосредственно сценарием Envision, но иногда простого определения типа недостаточно. Синтаксис Envision позволяет указать любой необходимый тип столбца.

Envision позволяет задавать основные ключи таблицы, перечисляя их в скобках сразу же после определения. Существует всего 7 допустимых комбинаций первичных ключей:
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, *]
Выражение A[*] задает таблицу, в которой вообще нет ограничений. Подстановочный знак позволяет применять самые разнообразные сценарии, но если столбец Id не указан, вы не сможете использовать некоторые полезные функции языка Envision.

Выражение B[Id] задает таблицу, в которой на одно наименование приходится не более одной строки. Например, наши параметры запасов попадают в эту категорию.

В случае с C[Id, *] таблица может содержать любое количество строк на одно наименование. Например, в данную категорию попадают таблицы, содержащие распределение вероятности.

В таблице D[Date] содержится единственное скалярное значение для определенных дней. Например, такая таблица может использоваться для составления списка государственных праздников для отдельных регионов.

В таблице E[Date, *] содержится любое количество скалярных значений для определенных дней. Это расширенный вариант предыдущей таблицы: здесь определенный день может быть связан с различными факторами.

Таблица F[Id, Date] содержит не более одного значения для каждой пары (Id, Date). Например, такая таблица может использоваться для составления списка случаев дефицита товара в прошлом.

Таблица G[Id, Date, *] является стандартной. Она отображается, если вы опускаете скобки. На практике в эту категорию попадает большинство исторических данных, например история продаж.

Типы ограничений по столбцам таблицы

Envision — строго типизированный язык. Это означает, что все векторы привязаны к одному из типов, доступных в Envision. В Envision доступно всего 4 типа: text, number, date и boolean, и эти типы обычно определяются непосредственно сценарием. Тем не менее можно указать ожидание типа следующим образом:
read "a.csv" as A[*] with
  "Foo" as X : text
  Y : number
  Z : date
Затем, возвращаясь к образцу набора данных, пропишем следующий код:
// эти три строки стандартные
// теперь их можно опускать
read "/sample/Lokad_Items.tsv"
read "/sample/Lokad_Orders.tsv" as Orders
read "/sample/Lokad_PurchaseOrders.tsv" as PO

Quantity = sum(Orders.Quantity)
Тогда вектору Orders.Quantity скрыто присваивается числовой тип, потому что только числа можно складывать. В результате, когда Envision анализирует файлLokad_Orders.tsv, ожидается, что столбец Quantity должен содержать значения, которые можно обрабатывать как числа. Если бы мы написали:
Nonsense = sum(Orders.Client)
Envision попробовал бы обработать столбец Client в файле Lokad_Orders.tsv как числа, и процесс дал бы сбой, потому что данный столбец содержит идентификаторы клиентов, которые не являются числами. Помимо механизма определения типа синтаксис Envision позволяет открыто указывать ожидаемый тип каждого столбца в каждой таблице. Например, для образца набора данных можно открыто указать типы с помощью следующих операторов:
expect Supplier : text
expect Orders.NetAmount : number
expect PO.ArrivalDate : date
Выражение просто составляется следующим образом: expect MyTable.MyColumn : type, где type — один из четырех доступных типов: text, number, date или boolean. Чаще всего приходится прописывать тип date, потому что с помощью арифметических операций и механизма определения типа не всегда получается точно сказать, что данные, содержащиеся в столбце, являются датами.

Варианты прочтения данных

Синтаксический анализатор файлов Envision — это универсальный инструмент, однако есть ситуации, когда ему нужна небольшая помощь. Оператор skip можно использовать для пропуска N первых строк простого файла. Синтаксис данной функции выглядит так:
read "/foo/bar*.csv" skip:2 as MyTable with
  "Foo1" as Id
  "Foo2" as Date
В примере выше анализатор пропускает первые две строки простого файла и делает заголовками столбцов данные, находящиеся в третьей строке. Оператор skip не является обязательным, по умолчанию значение данного параметра равно skip:0. Данная опция предназначена для систем, которые вводят метаданные в самом начале простых файлов.

Незащищенное прочтение

Синтаксический анализатор файлов Envision достаточно жесткий: если значение должно быть датой или числом, но оно не прочитывается как таковое, при использовании оператора read программа выдаст ошибку. Как правило, при возникновении таких ошибок в Envision рекомендуется выяснить, почему данные в файле повреждены. Система Envision распознает различные форматы дат и чисел, поэтому если она выдает ошибку, то, скорее всего, данные действительно повреждены. Повреждение данных может привести к возникновению самых разных ошибок. Если Envision выдает ошибку, то это обычно свидетельствует о проблеме, которая возникла где-то раньше.

Тем не менее при работе с большими наборами данных становится гораздо сложнее избежать мелких ошибок данных. Если поврежденные данные устарели, то их исправление может вообще быть бесполезным занятием. Именно для таких ситуаций в Envision был добавлен режим незащищенного прочтения файлов unsafe. Синтаксис показан ниже:
read "/foo/orders.tsv" unsafe with
  "My Id" as Id
  "My Date" as Date
При использовании оператора unsafe Envision рассматривает проблемы с прочтением данных как предупреждения, а не ошибки. Благодаря этой функции расчеты не будут прерываться, даже если значения или строки блокируются анализатором из-за того, что их невозможно прочитать.

FORMATTER ERROR (Transcluded inexistent page or this same page)