graflo

GraFlo — это библиотека Python, которая превращает записи из файлов, баз данных SQL, RDF, REST API или топиков Kafka в помеченный граф свойств. Вы описываете граф один раз, в файле YAML под названием манифест, и GraFlo создаёт схему и записывает вершины и рёбра в выбранную вами графовую базу данных или в каталог на диске. Она предназначена для инженеров, которые строят граф из нескольких источников и хотят, чтобы его описание находилось в одном проверяемом файле, а не было разбросано по скриптам загрузки. ## Что с её помощью можно делать - **Описать граф один раз и загружать в него данные.** Манифест задаёт имена типов вершин и рёбер, указывает, какие свойства идентифицируют вершину, и описывает, как каждый вид записи превращается в вершины и рёбра. Один и тот же манифест загружается в ArangoDB, Neo4j, TigerGraph, FalkorDB, Memgraph, NebulaGraph, PostgreSQL или файловый бэкенд, а записи с одинаковой идентичностью становятся одной вершиной. GraFlo также копирует существующий граф из Neo4j, ArangoDB или PostgreSQL в другую базу данных (`GraphEngine.migrate_graph`). - **Изменять описание со временем с записанной историей.** Переименование типа, объединение двух типов или изменение типа свойства — это типизированная операция. Операции записываются как коммиты (`graflo commit`, `log`, `checkout`, `verify`, `revert`), которые можно воспроизводить, проверять и, для большинства операций, отменять. Две ветви изменений одного манифеста согласуются трёхсторонним слиянием (`graflo merge3`), а два манифеста, написанные разными командами, объединяются в один с помощью union (`graflo merge`). - **Проверять и выводить описания.** GraFlo выводит манифест из базы данных PostgreSQL или онтологии OWL, предлагает свойства, идентифицирующие запись, на основе образца данных и проверяет манифест на соответствие профилю конформности (`graflo check`) — набору правил моделирования, таких как «каждый тип вершины объявляет свою идентичность». ## Пример Манифест состоит из трёх блоков: `schema` описывает, как выглядит граф, `ingestion_model` — как записи отображаются на него, а `bindings` — откуда берутся записи. Этот манифест читает CSV-файлы со столбцами `person_id`, `person` и `department`: ```yaml schema: metadata: {name: hr} graph: vertex_config: vertices: - {name: person, properties: [id, name], identity: [id]} - {name: department, properties: [name], identity: [name]} edge_config: edges: [{source: person, target: department}] ingestion_model: resources: - name: departments pipeline: - {vertex: person, from: {id: person_id, name: person}} - {vertex: department, from: {name: department}} bindings: connectors: - {regex: "^dep.*\\.csv$", sub_path: data, resource_name: departments} ``` Так он загружается в ArangoDB: ```python from graflo import GraphEngine, GraphManifest from graflo.connections import ArangoConfig manifest = GraphManifest.from_yaml("manifest.yaml") manifest.finish_init() engine = GraphEngine() engine.define_and_ingest(manifest=manifest, target_db_config=ArangoConfig.from_env()) ``` `ArangoConfig.from_env()` читает `ARANGO_URI`, `ARANGO_USERNAME`, `ARANGO_PASSWORD` и `ARANGO_DATABASE`; для каждой базы данных есть такой класс. См. [Подключения к базам данных](https://growgraph.github.io/graflo/guides/database_connections/). ## Документация Полная документация: [growgraph.github.io/graflo](https://growgraph.github.io/graflo) - [Быстрый старт](https://growgraph.github.io/graflo/getting_started/quickstart/): два CSV-файла в граф, шаг за шагом - [Создание манифеста](https://growgraph.github.io/graflo/getting_started/creating_manifest/): три блока манифеста - [Примеры](https://growgraph.github.io/graflo/examples/): запускаемые примеры, по одному вопросу в каждом, с их данными в каталоге [`examples/`](https://github.com/growgraph/graflo/tree/main/examples) - [Концепции](https://growgraph.github.io/graflo/concepts/): схема, идентичность, приём данных, коннекторы, эволюция и контроль версий - [Руководства](https://growgraph.github.io/graflo/guides/): подключения к базам данных, миграция графа, вывод схемы, подключение API, массовая загрузка - [Онтология GraFlo](https://growgraph.github.io/graflo/concepts/schema/ontology/): манифест как RDF (`graflo manifest-to-rdf`, `graflo rdf-to-manifest`) ## Установка GraFlo требует Python 3.11 или новее. Клиенты баз данных, поддержка RDF и Kafka входят в установку по умолчанию. ```bash pip install graflo ``` Дополнительные компоненты (см. руководство [Установка](https://growgraph.github.io/graflo/getting_started/installation/)): - `dev`: pytest и его плагины, hypothesis, ty, pre-commit - `docs`: ProperDocs и его плагины для сборки сайта документации - `plot`: `pygraphviz` для `graflo plot-manifest` и фигур `--plot` у `graflo merge` и `graflo merge3` ```bash pip install "graflo[dev,docs,plot]" ``` ## Разработка Чтобы установить из клона: ```shell git clone [email protected]:growgraph/graflo.git && cd graflo uv sync --extra dev ``` Полный рабочий процесс см. в [Руководстве по участию](https://growgraph.github.io/graflo/contributing/). ### Тесты Тестам баз данных нужны контейнеры баз данных. Запустите их из клона с помощью скриптов в каталоге [docker/](https://github.com/growgraph/graflo/tree/main/docker): ```shell cd docker ./start-all.sh # Start all services ./stop-all.sh # Stop all services ./cleanup-all.sh # Remove containers and volumes ``` Compose-файлы и порты для каждого движка описаны в [README docker](https://github.com/growgraph/graflo/blob/main/docker/README.md). Чтобы запустить тесты: ```shell uv run pytest test ``` Тесты TigerGraph, NebulaGraph и Kafka пропускаются, если не передать `--run-tigergraph`, `--run-nebula` или `--run-kafka`. Наборы, не требующие базы данных, работают без контейнеров, и CI запускает их при каждом pull request: ```shell uv run pytest test --ignore=test/db --ignore=test/data_source --ignore=test/object_storage ``` ## Лицензия Открытый исходный код под [Apache License 2.0](https://github.com/growgraph/graflo/blob/main/LICENSE). Уведомления об авторских правах и товарных знаках находятся в [NOTICE](https://github.com/growgraph/graflo/blob/main/NOTICE): лицензия не предоставляет никаких прав на знаки **GraFlo** и **GrowGraph**. Релизы до смены лицензии выпускались под Business Source License 1.1 и сохраняют эти условия; см. [changelog](https://github.com/growgraph/graflo/blob/main/CHANGELOG.md). ## Участие Вклад приветствуется. См. [Руководство по участию](https://growgraph.github.io/graflo/contributing/). Участники принимают [Соглашение о лицензии участника](https://github.com/growgraph/graflo/blob/main/CLA.md) один раз, комментируя свой первый pull request.