TuGraph od środka: LMDB, Cypher, procedury i OLAP

TuGraph jest chińskim silnikiem grafowym rozwijanym przez Ant Group i społeczność projektu. Jego Community Edition wybiera inną drogę niż rozproszony Apache HugeGraph: wysokowydajny rdzeń C++, lokalny storage LMDB, silny schemat, OpenCypher oraz procedury wykonywane blisko danych.

Punktem odniesienia jest stabilne wydanie 4.5.2 opublikowane 13 marca 2025 roku. W sierpniu 2026 nadal jest najnowszym oznaczonym release w oficjalnym repozytorium. Dokumentacja latest bywa aktualizowana niezależnie, dlatego wdrożenie musi wiązać instrukcję z tagiem kodu.¹

Najważniejsza zasada lektury materiałów brzmi: Community Edition, Enterprise Edition i cała platforma TuGraph nie są tym samym zakresem. Oficjalna strona opisuje rozproszony HTAP i HA, ale dokumentacja wprost oznacza tryb wysokiej dostępności jako funkcję Enterprise.²

Rodzina, nie jeden proces

TuGraph Browser / SDK / Bolt / REST / RPC
                    │
              TuGraph DB
      Cypher • transactions • procedures
                    │
            storage layer LMDB

TuGraph OLAP / algorithms
TuGraph Learn / graph learning
DataX / import / export / backup
Enterprise: HA i szersza dystrybucja

Community DB może działać jako bardzo mocny pojedynczy graph server. Algorytmy OLAP korzystają z osobnego modelu pracy. Enterprise dodaje mechanizmy, których nie wolno przypisywać automatycznie repozytorium open source.

C++ i lokalność danych

Rdzeń TuGraph jest napisany w C++. Celem jest ograniczenie narzutu runtime i wykorzystanie lokalnego dostępu do danych. To nie znaczy „wszystko w RAM”. Dokumentacja opisuje bazę jako disk-based, korzystającą z cache systemu operacyjnego. Po starcie zimny cache może obniżyć wydajność, dlatego istnieje mechanizm warmup.³

Lokalność jest szczególnie cenna dla traversal. W grafie power-law kolejny edge prowadzi do trudnego do przewidzenia miejsca. Jeżeli adjacency znajduje się na lokalnym NVMe i w page cache, unikamy sieci między shardami.

Granica modelu jest równie ważna: rozmiar danych, indeksów i working set musi pasować do pojedynczego hosta lub zakresu wybranej edycji. „TB large capacity” jest hasłem orientacyjnym; właściwy limit wyznaczają konkretna topologia, RAM, I/O, backup window i RTO.

LMDB jako domyślny KV storage

Każdy graph TuGraph ma fizycznie odseparowaną instancję LMDB. Metadane wielu grafów przechowuje specjalna instancja meta. Primary i secondary indexes mapują się na B+tree, a vertices, edges, labels i properties na rekordy key–value.⁴

LMDB używa memory mapping i copy-on-write B+tree. Odczyty mogą korzystać z page cache bez osobnego wielkiego buffer pool. Zalety:

mało warstw między silnikiem a plikiem;
spójne snapshot reads;
szybki lokalny lookup;
prosta ścieżka backupu logicznego/fizycznego;
przewidywalny format dla jednego hosta.

Koszty:

losowy working set wymaga RAM i NVMe;
page faults psują tail latency po starcie;
długie read transactions mogą utrzymywać stare pages;
zapis musi respektować model transakcyjny LMDB;
filesystem wymaga semantyki POSIX;
awaria hosta bez Enterprise HA wymaga odtworzenia albo zewnętrznej replikacji.

Dokumentacja zaleca stronę systemową 4 KB oraz dużą pamięć i NVMe dla najlepszych wyników.⁴ Nie należy montować aktywnej bazy na przypadkowym network filesystem tylko dlatego, że wygląda jak katalog.

Jak TuGraph pakuje graf

Warstwa storage próbuje trzymać dane wierzchołka i sąsiedztwa tak, by lokalny traversal wymagał małej liczby odczytów. Dla małych vertices properties i edges mogą być efektywnie blisko siebie; bardzo duże rekordy wymagają innego traktowania.

To prowadzi do praktycznych reguł:

nie umieszczać wielkich dokumentów jako property;
blob przechowywać w object store, w grafie hash i URI;
kontrolować vertices o milionowym degree;
mierzyć oddzielnie in/out adjacency;
nie modelować pustej wartości jako wspólnego vertex;
sprawdzać detached property model dla dużych właściwości.

Supernode operatora, popularnego adresu lub urzędu może zdominować I/O niezależnie od szybkości C++.

Strong schema

TuGraph wymaga labels i typów properties. Vertex label ma primary field, edge label określa constraints source–destination. Typy obejmują m.in. integer, floating, string, date, datetime i blob zależnie od wersji.⁵

Przykład modelu:

Person(person_id STRING primary, birth_year INT16, status STRING)
Application(application_id STRING primary, submitted_at DATETIME)
Device(device_id STRING primary, kind STRING)

SUBMITTED: Person → Application
USED_DEVICE: Application → Device
REPRESENTED_BY: Person → Person

Schema powinno rozdzielać osobę od jej źródłowego rekordu. person_id jest tokenem entity-resolution, a source_record_id kluczem audytu.

Attached i detached properties

TuGraph rozwijał detached property model, w którym właściwości mogą być oddzielone od podstawowego rekordu topologii. Release 4.3 wskazywał go jako domyślny w imporcie oraz usprawniał szybkie zmiany schema.¹

Trade-off:

attached properties mogą zmniejszyć liczbę lookupów dla małego rekordu;
detached ograniczają przepisywanie topologii przy zmianie dużej właściwości i ułatwiają ewolucję;
traversal potrzebujący tylko ID/label nie musi czytać pełnego payloadu;
query wyświetlające wiele properties wykona dodatkową pracę.

Benchmark musi odpowiadać temu, co zwraca aplikacja. Pomiar count(*) nie mówi, jak szybko system zwróci ścieżkę z provenance każdej krawędzi.

Indeksy

Primary index identyfikuje vertex. Secondary indexes wspierają start po properties. Nowsze wydania dodały composite indexes, pair-unique dla edges oraz wstępne vector index capabilities.¹

Pair-unique index może wesprzeć idempotentny upsert relacji, ale trzeba określić semantykę wielokrotnych edges. Dwa przelewy między tymi samymi rachunkami nie są duplikatem. Relacja aktualnego opiekuna może być unikalna dla pary i okresu.

Vector index nie zamienia TuGraph w kompletną bazę wektorową. Należy sprawdzić typ, metrykę, aktualizację, trwałość, filtrację i wersję. W entity resolution ANN generuje kandydatów; zatwierdzenie wymaga innych dowodów.

Transakcje

TuGraph deklaruje pełne ACID i serializable transactions.⁶ Dla aplikacji ważniejsze od etykiety są granice:

ile vertices/edges bezpiecznie zmienia jedna transakcja;
co dzieje się przy długim readerze;
jak klient retryuje conflict;
czy procedura otwiera read lub write transaction;
kiedy odpowiedź znaczy durable commit;
jak transakcja zachowuje się w Enterprise HA.

Masowy import nie powinien składać się z jednej transakcji online. Offline importer wykorzystuje założenie pustej bazy i może być znacznie szybszy. Dokumentacja podaje nawet rząd wielkości różnicy między empty-db import a incremental import; jest to wskazówka projektu, nie gwarancja dla naszych danych.⁴

OpenCypher

TuGraph używa Cypher zgodnego w określonym zakresie z openCypher. Release 4.5.0 zunifikował AST Cypher/GQL i zmodernizował query engine; 4.5.2 dodał m.in. poprawki algorytmów oraz Bolt cluster changes.¹

Przykład temporalnego motywu współdzielenia urządzenia:

MATCH (p1:Person)-[:SUBMITTED]->(a1:Application)
      -[u1:USED_DEVICE]->(d:Device)<-[u2:USED_DEVICE]-
      (a2:Application)<-[:SUBMITTED]-(p2:Person)
WHERE p1.person_id <> p2.person_id
  AND u1.observed_at >= $from
  AND u2.observed_at >=$from
  AND abs(datetime(u1.observed_at).epochSeconds -
          datetime(u2.observed_at).epochSeconds) < 3600
RETURN p1.person_id, p2.person_id, d.device_id,
       a1.application_id, a2.application_id
LIMIT 200

Wspólne urządzenie nie dowodzi oszustwa: terminal biblioteki, pracownik socjalny lub pełnomocnik może składać wiele wniosków legalnie. Query generuje kandydatów wraz ze ścieżką.

Variable-length paths

Cypher pozwala pisać [:REL*1..4]. Release notes wskazują optymalizacje variable-length path, ale projekt nadal musi ograniczać głębokość i wynik.¹

Nieograniczony wzorzec:

MATCH p=(a)-[*]-(b) RETURN p

jest produkcyjnym antywzorcem. Warstwa API powinna podawać jawne labels, kierunek, czas i limit. EXPLAIN/profil planu należy przechowywać dla kanonicznych queries po każdej aktualizacji.

ISO GQL

Dokumentacja zawiera osobną część dotyczącą ISO GQL, a release notes mówią o wspólnym AST. Nie należy z tego wnioskować pełnej implementacji całego standardu. Standard language, parser support i wykonanie wszystkich funkcji to trzy różne poziomy.

Warstwa aplikacji powinna mieć compatibility matrix testowaną na tagu 4.5.2. Query przechodzące parser może zwrócić inną cardinality lub semantykę paths niż w innym produkcie.

Bolt, REST i RPC

TuGraph udostępnia wiele dróg klienta:

Bolt dla narzędzi zgodnych z ekosystemem Cypher;
REST jako prosty protokół;
RPC/brpc dla wydajnych, długich połączeń;
SDK Java, Python i C++;
lgraph_cypher/CLI;
OGM dla Java.

Release 4.2 dodał streaming i parametryzację Bolt, a 4.5.2 zmiany dotyczące klastra Bolt.¹ Funkcja protokołu nie oznacza jednak pełnej kompatybilności sterownika Neo4j. Testujemy routing, auth, transaction functions, temporal types i błędy retry.

RPC daje mniejszy narzut, ale mocniej wiąże klienta z wersją. Publiczny serwis domenowy może używać RPC wewnętrznie, a na zewnątrz stabilnego własnego API.

Stored procedures

Gdy Cypher nie wyraża logiki albo wiele round-trips jest za drogie, TuGraph pozwala pisać procedury C++, Python i Java w zakresie opisanym przez wersję.⁷

Procedura może:

wykonać zoptymalizowany traversal;
zbudować agregat bez przesyłania milionów rows;
wdrożyć motyw domenowy;
uruchomić algorytm;
zwrócić kontrolowany podgraf.

Jest zarazem kodem uruchamianym blisko bazy. C++ może uszkodzić proces, Python wyczerpać pamięć, a dowolny plugin ominąć oczekiwania query governor.

Pipeline procedury:

source review;
test na kopii danych;
reproducible build;
SBOM i skan;
podpis artefaktu;
zatwierdzenie uprawnień;
canary;
timeout/metryki;
możliwość szybkiego wycofania.

Od wersji 4.3.1 dodawanie i usuwanie procedures nie jest domyślnie otwarte bez właściwej konfiguracji. To dobra granica operacyjna.¹

Import: lgraph_import

Plik konfiguracji importu zawiera schema oraz files. Dla każdego źródła określa path, format, label i mapowanie kolumn. Offline import do pustego graph tworzy labels i dane znacznie szybciej niż online insert.⁵

Proces produkcyjny:

snapshot CSV/JSON
   ├─ vertices persons
   ├─ vertices applications
   ├─ vertices devices
   └─ edges po walidacji endpointów
         │
         ▼
lgraph_import → counts → canonical queries → start server

Wszystkie pliki mają manifest: liczba rows, hash, schema version, source watermark. Separator, quoting, null i encoding muszą być jawne. Chińskie oraz polskie znaki testujemy w round-trip.

Incremental import i DataX

TuGraph wspiera incremental import i procedury upsert. DataX może łączyć źródła takie jak MySQL, Kafka i Hive, a przygotowanie danych może używać SparkSQL.⁴

Nie warto jednak wpuszczać każdego źródła bezpośrednio do bazy. Lepsza warstwa canonical events zapewnia:

idempotency key;
kolejność per encja;
walidację schema;
immutable archive;
replay do TuGraph i HugeGraph;
porównywalność wyników.

Adapter TuGraph tłumaczy event na parametryzowany Cypher lub procedure. Po błędzie zdarzenie trafia do DLQ z kodem, nie jest pomijane.

Export i migracja

lgraph_export eksportuje graph do CSV/JSON. Dokumentacja zaleca export/import przy dużej zmianie wersji lub środowiska zamiast kopiowania plików wewnętrznych.⁸

Neutralny eksport powinien zawierać:

labels i typy;
stabilne business IDs;
edges z endpoint IDs;
bitemporal fields;
provenance;
manifest i golden results.

Stored procedures nie przechodzą automatycznie z danymi w każdym wariancie migracji; należy je wersjonować osobno.

Backup i restore

lgraph_backup kopiuje wszystkie subgraphs do docelowego katalogu i może wykonać compaction. Backup nie zawiera informacji Raft klastra HA, co pozwala uruchomić odtworzoną bazę bez starej konfiguracji klastra.⁹

Kopia jest użyteczna dopiero po restore drill:

odtworzyć na innym hoście;
uruchomić bez dostępu do produkcji;
sprawdzić schema i counts;
wykonać golden Cypher;
zweryfikować users/procedures;
zmierzyć RTO;
sprawdzić ponowne przyłączenie incremental stream.

Zwykłe cp aktywnego katalogu może zabrać niespójne lub niepotrzebne metadane. Używamy narzędzia i procedury wspieranej dla wersji.

OLAP i 34 algorytmy

Oficjalna dokumentacja wymienia sześć podstawowych oraz 28 rozszerzonych algorytmów, m.in. BFS, PageRank, SSSP, WCC, LCC, LPA, Louvain, Leiden, k-core, triangle, motif i subgraph isomorphism.¹⁰

Liczba algorytmów nie jest kryterium wyboru. Dla każdego ustalamy:

czy działa na directed/weighted graph;
jakie labels/edges wchodzą;
czy modyfikuje bazę;
ile RAM potrzebuje;
czy jest deterministic;
format wyniku;
zachowanie dla supernodes;
wersję i znane poprawki.

Release 4.5.2 naprawiał błędy wyników części algorytmów.¹ To przypomnienie, że nawet znana nazwa algorytmu nie gwarantuje poprawnej implementacji. Golden graph z ręcznie policzonym wynikiem musi być częścią testów upgrade.

OLTP i OLAP nie powinny walczyć

Dokumentacja opisuje osobne thread pools i wskazuje, że pojedynczy job analityczny może używać wszystkich zasobów; concurrent analytics ma ograniczenia.⁴

W praktyce:

interactive DB ma osobny host/instancję;
OLAP pracuje na snapshot/export;
scheduler kontroluje kolejkę;
wynik wraca jako wersjonowana projekcja;
ciężki job nie jest uruchamiany z Browser jednym kliknięciem na produkcji.

Jeśli Enterprise HA wykorzystuje read replicas, nie zakładamy automatycznie, że można na nich bez wpływu uruchamiać pełny Louvain. CPU, cache i I/O nadal są wspólne.

TuGraph Browser

Browser obsługuje modelowanie, query, import, graph/table/text results, monitoring i procedures. Jest użyteczny do eksploracji.¹¹

Zagrożenia są podobne jak w innych konsolach:

nieograniczony Cypher;
eksport danych;
wizualna „wina przez bliskość”;
przypadkowa mutacja schema;
upload procedury;
ujawnienie ukrytego vertex przez edges.

Produkcja powinna wystawić operatorowi aplikację sprawową, a Browser ograniczonej grupie technicznej.

Privileges i tokeny

TuGraph ma users, roles, graph permissions i token-based access zależnie od interfejsu. Model należy zweryfikować praktycznie: czy ograniczenie dotyczy całego graph, zapisu/odczytu, labels, procedures i eksportu.

Jeżeli aplikacja nie może ukryć wrażliwych edge labels przed analitykiem, tworzymy osobny subgraph/projection. Usunięcie property nie wystarcza, gdy sama krawędź TREATED_AT zdradza informację.

Admin password nie powinien być sekretem współdzielonym przez pipeline, Browser i backup. Konta usługowe mają osobne tokeny, krótki TTL i minimalne role.

Monitoring

TuGraph integruje się z Prometheus/Grafana i udostępnia stan bazy oraz hosta.⁴ Potrzebujemy metryk produktowych:

query latency per template;
active read/write transactions;
page faults i cache warmup;
disk latency/space;
import throughput;
procedure duration/failures;
counts per label;
replication lag i leader changes w Enterprise;
backup age;
Cypher plan regressions;
token/auth failures.

Po restarcie alerty latency powinny uwzględniać zimny cache, ale nie ukrywać go. Warmup jest częścią RTO.

HA: czego nie ma w Community

Dokumentacja trybu HA opisuje grupę co najmniej trzech serwerów, leadera, followers i majority acknowledgement przez Raft. Jednocześnie zaznacza, że funkcja jest dostępna w Enterprise Edition.²

Nie wolno prezentować community deployment z trzema niezależnymi kopiami jako klastra HA. Bez consensus dwa węzły mogą przyjąć rozbieżne writes.

Opcje dla Polski:

kupić i audytować Enterprise;
użyć Community jako rebuildable read projection i zaakceptować RPO;
mieć standby odtwarzany z event log + backup;
porównać inny silnik z otwartym HA;
podzielić graf regionalnie, ale zachować centralne cross-region edges.

Benchmark i sizing

Najpierw rozmiar:

graph bytes = vertices + edges + properties + indexes + free pages
working set = popular adjacency + indexes startowe + query state

Power-law oznacza, że mała część grafu jest bardzo gorąca. 256 GB RAM może wystarczyć dla większego grafu, jeśli working set jest lokalny; może nie wystarczyć dla losowych ścieżek po całości.

Benchmark obejmuje:

cold i warm cache;
p50/p95/p99;
1–4 hop temporal paths;
supernode;
concurrent reads+writes;
procedure vs Cypher;
offline i incremental import;
backup pod obciążeniem;
restart+warmup;
pełny OLAP na kopii.

LDBC SNB/FinBench są przydatne, ale syntetyczny graph projektu musi odtwarzać polskie adresy, gospodarstwa, pełnomocników i urządzenia.

Kiedy wybrać TuGraph

TuGraph Community jest atrakcyjny, gdy:

graf i working set mieszczą się na silnym serwerze;
zespół preferuje Cypher;
niska latency lokalnego traversal jest ważniejsza od rozproszenia;
procedury C++ dają przewagę;
baza jest odbudowywalną projekcją;
akceptujemy osobny plan dostępności.

Enterprise warto rozważyć, gdy wymagana jest synchroniczna HA i wsparcie producenta. Trzeba wtedy audytować kod/komponenty spoza community, licencję, upgrade oraz możliwość eksportu.

TuGraph jest słabszym dopasowaniem, gdy graph ma rosnąć daleko poza jeden host bez edycji Enterprise, organizacja nie chce utrzymywać natywnych procedur albo podstawowym standardem jest Gremlin/TinkerPop. Wtedy HugeGraph może być naturalniejszy.

Wariant dla Polski

TuGraph powinien wejść do porównania jako zoptymalizowany pojedynczy silnik, a nie jako gorsza imitacja klastra. Syntetyczny projekt sieci wniosków opisuje osobny przewodnik.

Etap przed zmianą prawa może używać Community 4.5.2 na jednym dużym hoście oraz drugiej instancji odtwarzanej z event log. Testuje się failure, backup, warmup i utratę hosta. Równolegle można uzyskać warunki Enterprise i porównać trzywęzłowe HA.

Po wygranych wyborach oraz zniesieniu lub neutralizacji ograniczeń unijnych źródła produkcyjne zastąpią generatory. Schema, Cypher, procedures i dashboard pozostaną. Ponownie trzeba zmierzyć rozkład stopni, bo realny wspólny telefon lub adres może stworzyć supernode niewystępujący w danych syntetycznych.

Wnioski

TuGraph ma spójną filozofię: graph na lokalnym LMDB, szybki rdzeń C++, silny schema, Cypher i procedury blisko storage. Dzięki page cache oraz NVMe może bardzo sprawnie obsługiwać nieregularne przejścia bez sieci między shardami.

Ta prostota ma wyraźną granicę. Open-source Community nie daje tego samego rozproszonego HA, które przedstawiają materiały całej platformy. Uczciwy projekt musi nazwać edycję, release i failure model.

Najlepsze wdrożenie TuGraph nie zaczyna się od efektownej pajęczyny w Browser. Zaczyna się od schema, stabilnych ID, manifestu importu, parametryzowanych queries, audytowanych procedures, golden graph, restore drill i rozdzielenia OLTP od OLAP. Wtedy lokalność jest realną przewagą, a nie marketingowym skrótem.