Apache HugeGraph jest otwartym stosem grafowym, nie tylko plikiem JAR z bazą. Łączy silnik OLTP, API, języki zapytań, import, wizualizację, narzędzia operacyjne i obliczenia całego grafu. Ta szerokość jest jego największym atutem i źródłem najczęstszych nieporozumień.

W tym artykule punktem odniesienia jest wydanie 1.7.0, wskazywane przez projekt jako aktualne stabilne w sierpniu 2026 roku. Linie wcześniejsze mają inne endpointy, listy backendów i ograniczenia. Konfiguracji znalezionej w blogu dla 0.12 lub 1.3 nie należy bez testu przenosić do 1.7.1

Teorię vertices, edges, czasu, supernodes i algorytmów opisuje osobny artykuł. Tutaj interesuje nas to, jak HugeGraph te pojęcia implementuje i jak utrzymać go jako element platformy państwowej.

Od projektu chińskiego do Apache TLP

HugeGraph rozwijano pierwotnie w Chinach, a następnie przekazano do Apache Software Foundation. Po okresie inkubacji projekt został Top-Level Project na początku 2026 roku.2

Status Apache oznacza otwarty proces governance, licencję Apache 2.0, publiczne wydania, listy mailingowe i reguły podpisywania artefaktów. Nie jest certyfikatem jakości konkretnego wdrożenia. Operator nadal odpowiada za konfigurację, patching, backup i test zachowania pod swoim workloadem.

Ważny detal supply-chain: dokumentacja zaznacza, że obrazy Docker są wygodnym sposobem uruchomienia, ale nie są oficjalnymi artefaktami dystrybucyjnymi ASF. Produkcja powinna pinować tag, digest, SBOM i podpis, a nie używać latest.1

Mapa komponentów

aplikacje / analitycy / pipeline
        │
        ├─ Java/Python/Go client
        ├─ REST / Gremlin / Cypher
        └─ Hubble
                │
        HugeGraph Server (OLTP)
        schema • query • auth • tasks
                │ backend interface
      ┌─────────┼──────────┐
    RocksDB    HStore      HBase
  standalone distributed  zależnie od wersji

Loader / Tools ─ import, backup, restore
Computer / Vermeer ─ OLAP
HugeGraph-AI ─ GraphRAG i graph ML

Nie wszystkie komponenty muszą działać w jednym wdrożeniu. Prosty graf analityczny może używać Server+RocksDB i klienta. Wielki system dodaje HStore, Loader, monitoring i osobny OLAP. Hubble nie powinien automatycznie znaleźć się w strefie produkcyjnej tylko dlatego, że jest częścią ekosystemu.

Server: control plane i data plane w jednym procesie logicznym

HugeGraph Server udostępnia operacje schema, graph data, Gremlin, Cypher, traversers, tasks, authentication i metrics. Implementuje model Apache TinkerPop 3 dla OLTP.3

Warstwa REST upraszcza integrację, ale generuje dwa typy obciążenia:

  • krótkie CRUD i parametryzowane traversals;
  • dowolne skrypty lub kosztowne zapytania analityka.

Nie powinny korzystać z tej samej puli bez limitów. Publiczna aplikacja powinna wywoływać zamknięty katalog endpointów domenowych. Konsola Gremlin należy do wydzielonej sieci, roli i limitu zasobów.

Graphspaces w 1.7

Linia 1.7 wprowadziła graphspaces jako warstwę organizacji i izolacji wielu grafów. Nowe ścieżki REST mają postać:

/graphspaces/{graphspace}/graphs/{graph}/...

Starsze przykłady używają /graphs/{graph}/.... Domyślny graphspace nazywa się DEFAULT.4

Graphspace pomaga rozdzielić projekty lub tenantów, ale nie zastępuje pełnej separacji. Trzeba sprawdzić:

  • współdzielenie JVM i thread pools;
  • backend storage oraz katalogi;
  • granice użytkowników i ról;
  • limity pamięci i zadań;
  • wpływ backupu i index rebuild jednego grafu na inne.

Dla danych o różnych klauzulach lepsze mogą być osobne instancje i klucze. Logical tenancy jest właściwa dla zespołów o podobnym poziomie zaufania, nie dla wszystkiego w państwie.

Schema: cztery rodzaje definicji

PropertyKey

Definiuje nazwę, typ i cardinality właściwości. Data zapisana raz jako liczba epoch, a raz jako tekst zniszczyłaby temporal query; schema ma temu zapobiec.

Warto od początku ustalić:

  • identyfikatory jako tekst bez semantyki liczbowej;
  • czas w jednej strefie/UTC i jawnej jednostce;
  • kwoty jako integer najmniejszej jednostki lub decimal strategy;
  • wielowartościowe pola tylko wtedy, gdy naprawdę są właściwością, a nie encją;
  • source_record_id, assertion_type i lineage na relacjach.

VertexLabel

Określa typ vertex, properties, nullable keys, primary keys i ID strategy. Person, Organization, Document i SourceRecord powinny być osobnymi labels.

EdgeLabel

Definiuje source label, target label, frequency, properties, sort keys i nullable keys. HugeGraph pozwala więc wyrazić, że OWNS biegnie z Person do Organization, a nie dowolnie.

Frequency ma znaczenie: pojedyncza relacja między parą vertices i wielokrotne zdarzenia to inne modele. Dla TRANSFERRED_TO potrzebujemy wielu edges rozróżnianych np. transaction_id lub czasem; dla aktualnego HAS_PRIMARY_ID zwykle jednej aktywnej.

IndexLabel

Indeks wiąże się z vertex/edge label i polami. Dokumentacja wyróżnia m.in. indeksy secondary oraz range. Utworzenie indeksu może uruchomić asynchroniczny task, którego status trzeba monitorować.5

Nie indeksujemy wszystkiego. Każdy indeks zwiększa write amplification, czas importu i rozmiar. Indeks powinien odpowiadać realnemu starting point zapytania.

ID strategy

HugeGraph może generować ID albo wyprowadzać je z primary keys. Dokumentacja pokazuje, że primary-key strategy daje deterministyczne ID i automatyczną deduplikację.6

Dla syntetycznej osoby można użyć technicznego person_token. Dla źródłowego rekordu dobrym kluczem jest (source_system, source_record_id). Nie należy wkładać PESEL bezpośrednio do URL, logów i identyfikatora wewnętrznego.

Deterministyczność ułatwia idempotentny import, ale zmiana primary key staje się migracją vertex. Stabilny klucz techniczny powinien przetrwać korektę nazwiska, adresu i dokumentu.

Gremlin jako główny sposób myślenia

Gremlin tworzy traversal z kroków. Przykład znalezienia organizacji kontrolowanych do trzech poziomów:

g.V().has('Person', 'person_token', token)
 .repeat(
   outE('OWNS', 'CONTROLS')
    .has('valid_from', lte(at))
    .filter(or(hasNot('valid_to'), has('valid_to', gt(at))))
    .inV()
    .simplePath()
 )
 .emit()
 .times(3)
 .hasLabel('Organization')
 .path()
 .by(valueMap(true))
 .limit(100)

Kolejność kroków ma konsekwencje. Filtr edge przed inV() ogranicza rozwinięcie wcześniej. path() materializuje historię, dedup() może wymagać dużego stanu, a order() przed limit() często sortuje ogromny zbiór.

Production query powinno mieć:

  • indeksowany start;
  • jawne edge labels i kierunki;
  • limit głębokości;
  • filtr czasu;
  • simplePath lub kontrolę cyklu;
  • limit wyników;
  • timeout i budżet visited edges;
  • parametr zamiast konkatenacji kodu.

Skrypt Gremlin a bytecode

Wysłanie tekstu do endpointu Gremlin jest proste, lecz parser wykonuje kod w kontekście serwera. Klient TinkerPop może budować traversal/bytecode, co ogranicza część problemów z wstrzyknięciem i ułatwia parametryzację.

Nie należy zakładać, że każdy krok TinkerPop zachowa identyczną wydajność na każdym backendzie. Provider może implementować optymalizacje i ograniczenia inaczej. Golden tests powinny sprawdzać wynik, a benchmark — plan i koszt.

Cypher w HugeGraph

Aktualna dokumentacja 1.7 deklaruje Gremlin i Cypher/OpenCypher. Endpoint Cypher jest wygodny dla zespołów myślących wzorcami. Nie oznacza pełnej zgodności ze wszystkimi rozszerzeniami Neo4j ani przyszłym ISO GQL.3

Przed migracją sprawdzamy:

  • obsługę variable-length paths;
  • semantykę null;
  • parametry i typy;
  • update clauses;
  • procedures/functions;
  • planowanie indeksów;
  • transakcje wielu instrukcji;
  • zwracanie pełnych paths.

W nowym projekcie warto wybrać jeden podstawowy język. Utrzymywanie tej samej reguły w Gremlin i Cypher bez testów prowadzi do rozjazdu semantyki.

Traverser API

HugeGraph udostępnia wyspecjalizowane endpointy dla shortest path, k-neighbors, similarity i innych operacji.4 Mogą być bezpieczniejsze oraz łatwiejsze do ograniczenia niż dowolny skrypt.

Warstwa aplikacyjna może mapować domenowe operacje:

GET /persons/{id}/ownership-paths?at=...&maxDepth=4
POST /cases/{id}/shared-resources
GET /organizations/{id}/shortest-listed-path

na zatwierdzone traversers. Użytkownik nie dostaje pola gremlin=. Serwis zapisuje template ID, parametry, wersję schema, liczbę odwiedzonych elementów i wynik.

Loader: initial load jako osobny produkt

HugeGraph-Loader mapuje pliki lub źródła na vertices i edges. Konfiguracja wskazuje graph, graphspace, schema script i strukturę danych. W 1.7 wersje Server, Client, Loader i Hubble są wyrównywane.7

Poprawna kolejność:

  1. zamrozić snapshot źródeł;
  2. utworzyć schema;
  3. załadować vertices źródłowe;
  4. załadować resolved entities;
  5. załadować edges o stabilnych endpointach;
  6. zebrać rejects;
  7. sprawdzić counts i hashes;
  8. dograć CDC od watermark;
  9. dopiero potem przełączyć ruch.

Loader nie powinien po cichu pomijać edge do brakującego vertex. Reject ma source row, kod błędu i możliwość replay. Próg błędów może zatrzymać całą partię.

Import online i graph writer

Po initial load zdarzenia trafiają przez Kafka/RocketMQ do graph writer. Writer:

  • deduplikuje po event_id;
  • pilnuje aggregate_version;
  • tworzy brakujący SourceRecord;
  • zamyka valid_to starej relacji;
  • dodaje nową wersję;
  • zapisuje offset i manifest batcha;
  • publikuje wynik lub DLQ.

Nie wykonujemy dual write z aplikacji równocześnie do systemu źródłowego i grafu. Transakcja nie obejmuje obu baz; awaria stworzy rozbieżność. Outbox/CDC daje możliwość replay.

RocksDB: wariant standalone

RocksDB jest domyślnym backendem standalone w linii 1.7. To LSM-tree zoptymalizowane pod szybkie zapisy i lokalny storage. Memtables trafiają do SSTables, a compaction porządkuje poziomy.

Konsekwencje operacyjne:

  • NVMe ma duże znaczenie;
  • compaction zużywa I/O i CPU;
  • write amplification zależy od workloadu;
  • cache i block size wpływają na traversal;
  • backup plików bez spójnego mechanizmu może być wadliwy;
  • jedna maszyna tworzy granicę pojemności i HA.

Standalone jest dobry dla development, grafu regionalnego lub workloadu mieszczącego się na jednym serwerze. Nie należy go automatycznie odrzucać: lokalne traversal może być szybsze niż rozproszony odczyt. Trzeba jednak mieć plan awarii hosta.

HStore, PD i Store

HStore jest rozproszonym backendem HugeGraph. W architekturze pojawiają się Placement Driver i procesy Store, a Server komunikuje się z warstwą storage. Dokumentacja 1.7 zawiera uwagi konfiguracyjne zależne od wydania, np. scheduler zadań dla HStore.8

Rozproszenie daje skalę i replikację, ale dodaje:

  • consensus/metadata control plane;
  • placement partycji;
  • sieciowe traversals;
  • rebalance;
  • hotspoty;
  • zgodność wersji Server–PD–Store;
  • trudniejsze backup i rolling upgrade.

Benchmark musi odtwarzać cross-partition paths. Test, w którym wszystkie vertices jednej społeczności przypadkiem lądują na jednym Store, jest zbyt optymistyczny.

HBase i backendy historyczne

Dokumentacja 1.7 wymienia HBase, ale starsze wersje obsługiwały również MySQL, PostgreSQL czy Cassandra w innych zakresach. Lista „HugeGraph supports X” bez numeru wersji jest niewystarczająca.3

Backend plugin nie gwarantuje tych samych transakcji, indeksów i wydajności. Migracja z HBase do HStore powinna odbywać się przez neutralny export/rebuild oraz golden queries, nie przez kopiowanie wewnętrznych tabel.

Hubble: narzędzie analityka, nie dowód

Hubble pomaga tworzyć schema, importować, uruchamiać zapytania i wizualizować podgraf. Jest świetny w eksploracji i szkoleniu.

W produkcji wymaga:

  • SSO/MFA lub dodatkowej bramy;
  • ograniczonego network path;
  • read-only roles dla większości użytkowników;
  • limitów renderowanych vertices;
  • blokady niezatwierdzonych skryptów;
  • audytu eksportu;
  • wyłączenia danych surowych w tooltipach.

Force-directed layout nie jest algorytmem dowodowym. Zapis sprawy powinien zawierać query i listę edges, nie sam screenshot.

Computer i Vermeer

HugeGraph-Computer implementuje rozproszony model obliczeń grafowych typu Pregel, z supersteps i wymianą wiadomości. Vermeer jest pozycjonowany jako memory-first engine dla szybkich obliczeń. Dokumentacja pełnego stosu rozróżnia OLTP Server od OLAP.9

PageRank, connected components czy community detection nie powinny konkurować z interaktywnymi zapytaniami o tę samą pamięć. Typowy przepływ:

  1. utworzyć snapshot/watermark;
  2. przefiltrować labels, edge types i czas;
  3. uruchomić job OLAP;
  4. zapisać wynik z algorithm, parameters, snapshot_id i run_id;
  5. opublikować tylko zatwierdzone properties;
  6. wygasić wynik po zmianie modelu.

Wynik community_id=17 nie jest trwałą cechą osoby. Po dodaniu danych numer i granice mogą się zmienić.

HugeGraph-AI

Ekosystem rozwija GraphRAG i graph machine learning. Może budować knowledge graph z dokumentów, embeddings i retrieval. W systemie administracyjnym trzeba oddzielić:

  • graf faktów z rejestrów;
  • graf wzmianek wydobytych przez model;
  • graf embedding similarity;
  • odpowiedź językową.

LLM nie może tworzyć OWNS na podstawie luźnej wzmianki. Powinien utworzyć assertion MENTIONED_ASSOCIATION z dokumentem, fragmentem, modelem i confidence, oczekującą na weryfikację.

Authentication i authorization

Konfiguracja może używać HugeFactoryAuthProxy i StandardAuthenticator. API obejmuje users, groups, targets i permissions zależnie od wersji.10

Minimalne role:

  • schema administrator;
  • ingestion writer;
  • application reader dla określonych templates;
  • analyst z ograniczoną konsolą;
  • auditor logów;
  • backup operator bez prawa do analizy treści.

Sekretów nie zapisujemy w plikach Loader ani historii powłoki. Transport wymaga TLS/mTLS, a same endpointy nie powinny nasłuchiwać publicznie. Graph data może ujawnić relację nawet bez właściwości, więc authorization tylko per property bywa niewystarczające; czasem trzeba osobnej projekcji.

Query governance

Dowolny traversal jest odpowiednikiem kosztownego programu. Kontrolujemy:

  • maksymalny czas;
  • liczbę wyników;
  • głębokość repeat;
  • dozwolone labels;
  • pamięć na path/dedup/group;
  • jednoczesność;
  • priorytet;
  • rozmiar odpowiedzi;
  • możliwość uruchamiania lambdas/skryptu.

Endpoint domenowy powinien najpierw oszacować koszt albo co najmniej odrzucić nieograniczony start. g.V().repeat(both()).emit() nie jest niewinnym zapytaniem.

Backup i restore

HugeGraph-Tools może eksportować schema, vertices i edges do JSON i odtwarzać je w trybie RESTORING lub MERGING. Logical backup jest przenośny, lecz przy wielkim grafie może trwać długo.11

Pełny plan zawiera:

  • backend-native snapshot dla szybkiego recovery;
  • logical export dla migracji;
  • schema i index definitions;
  • users/roles oraz sekrety poza backupem;
  • plugins i wersje;
  • manifest offsetów zdarzeń;
  • golden queries;
  • regularny restore na izolowanej instancji.

Tryb MERGING może zmienić IDs. Aplikacja oparta na wewnętrznych ID musi to uwzględnić. Stabilne business tokens i mapowanie są bezpieczniejsze.

Rebuild zamiast naprawiania wszystkiego w miejscu

Graf jest projekcją. Gdy zmienia się schema lub entity resolution:

graphspace/projekt-v1 ─ ruch produkcyjny
graphspace/projekt-v2 ─ snapshot + replay + testy
                         │
                         └─ shadow queries
po akceptacji: router v1 → v2

Blue–green wymaga podwójnego storage, ale daje rollback i porównanie. In-place mutation wieluset milionów edges jest trudniejsza do zweryfikowania.

Monitoring i SLO

Oprócz CPU/RAM/dysku mierzymy:

  • p50/p95/p99 per template;
  • visited vertices/edges;
  • Gremlin timeouts;
  • task queue i index rebuild;
  • Loader throughput/rejects;
  • compaction i write stalls RocksDB;
  • HStore partition skew i network;
  • liczby vertices/edges per label;
  • lag względem Kafka;
  • rozmiar odpowiedzi;
  • auth failures i eksporty.

SLO dla lookup może wynosić setki milisekund, dla ścieżki kilka sekund, a dla OLAP godziny. Mieszanie ich w jedną średnią latency niczego nie mówi.

Benchmark

Benchmark powinien pinować 1.7.0, JVM, backend, schema, dataset seed i konfigurację durability. Workload obejmuje lookup, 1-hop, 4-hop temporal path, motyw, supernode attack, write, rebuild, backup i awarię Store.

Należy raportować także koszt:

  • liczba serwerów;
  • RAM i NVMe;
  • rozmiar indeksów;
  • czas initial load;
  • czas rebalance;
  • RPO/RTO;
  • operator-hours.

Producent może wykazać miliardy edges, lecz państwo potrzebuje przewidywalności swoich paths oraz restore.

Kiedy wybrać HugeGraph

HugeGraph jest mocnym kandydatem, gdy:

  • zespół zna Gremlin/TinkerPop;
  • potrzebna jest otwarta warstwa backendów;
  • plan obejmuje graf większy niż jeden host;
  • przydatny jest Loader, Hubble i osobny OLAP;
  • akceptujemy JVM i złożoność pełnego stosu;
  • chcemy Apache governance zamiast jednego producenta.

Nie jest oczywistym wyborem, gdy cały graf mieści się na jednej maszynie, zespół zna wyłącznie Cypher, potrzebuje prostego HA community i nie ma kompetencji do utrzymania PD/Store. Wtedy TuGraph albo inny silnik może wygrać.

Wariant dla Polski

Pierwszy etap powinien używać HugeGraph 1.7 standalone/RocksDB na danych syntetycznych, ale z produkcyjnym schema, auth, TLS i event writerem. Następnie benchmark porównuje:

  • większy pojedynczy node;
  • HStore w trzech failure domains;
  • alternatywny produkt na identycznym golden workloadzie.

Praktyczny projekt sieci wpływu opisuje kolejny artykuł HugeGraph. Jego wartość polega na tym, że schema, Loader mappings, Gremlin i wyniki testowe możemy rozwijać już dziś na generatorze danych.

Po zmianie politycznej i neutralizacji barier unijnych adaptery otrzymają realne źródła. Rdzeń HugeGraph nie musi wtedy zostać przepisany. Trzeba natomiast ponownie skalibrować entity resolution, popularność supernodes, query budgets i infrastrukturę.

Wnioski

HugeGraph oferuje rzadko spotykany otwarty pełny stos: Server, schema, Gremlin/Cypher, graphspaces, Loader, Hubble, Tools i obliczenia OLAP. Wersja 1.7 porządkuje komponenty, ale wprowadza też breaking differences względem starszych poradników.

Najważniejsze decyzje nie brzmią „czy HugeGraph obsługuje miliardy”. Brzmią:

  • jaki backend i failure model wybieramy;
  • gdzie przebiega granica graphspace;
  • które zapytania są dozwolone;
  • jak zasilamy graf bez dual write;
  • jak odtwarzamy go ze źródeł;
  • jak mierzymy cross-partition paths;
  • jak oddzielamy fakt od inference.

Jeśli te odpowiedzi są jawne, HugeGraph może być solidnym rdzeniem wielkiej analizy powiązań. Jeśli nie, bogaty katalog komponentów jedynie zwiększy powierzchnię awarii.