Przejdź do treści
Biblioteka skilli
Dane i analityka · Integracja z narzędziem

graph-source

/graph-source

Łączy graf właściwości (Apache AGE, openCypher, GraphRAG) ze Skardi i prowadzi przez konfigurację źródła, widoków i zapytań Cypher przez SQL.

Repozytorium
skardi-skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
23.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Łączy graf właściwości (Apache AGE, openCypher, GraphRAG) ze Skardi i prowadzi przez konfigurację źródła, widoków i zapytań Cypher przez SQL.

Oryginalny opis (EN)

Connect a property graph (knowledge graph, GraphRAG corpus, Apache AGE / openCypher data) to Skardi and query it through SQL, end to end: provision the AGE backend with a least-privilege role, declare the `type: graph` source and its views in context YAML, verify registration health, write correct queries (`cypher_query`, `graph_schema`, the JSON getters), and wire Cypher parameters into pipelines. Use this skill whenever the user wants graph data queryable in Skardi, mentions graphs, Cypher, AGE, Neo4j-style data, knowledge graphs, GraphRAG, `kg.*` tables, `cypher_query`, or is debugging a de

Jak działa

  1. The workflow
  2. Working style
Sekcje z nagłówków SKILL.md, w oryginale · 136 linii, 931 słów
Podgląd SKILL.md
---
name: graph-source
description: >-
  Connect a property graph (knowledge graph, GraphRAG corpus, Apache AGE /
  openCypher data) to Skardi and query it through SQL, end to end: provision
  the AGE backend with a least-privilege role, declare the `type: graph`
  source and its views in context YAML, verify registration health, write
  correct queries (`cypher_query`, `graph_schema`, the JSON getters), and
  wire Cypher parameters into pipelines. Use this skill whenever the user
  wants graph data queryable in Skardi, mentions graphs, Cypher, AGE,
  Neo4j-style data, knowledge graphs, GraphRAG, `kg.*` tables,
  `cypher_query`, or is debugging a degraded graph source, a
  `RowCapExceeded`, or a silently-NULL property column — even if they never
  say the words "graph source".
metadata:
  skardi-min-version: "0.6.0"
---

# Connecting a graph source to Skardi

You are wiring a property graph into Skardi as SQL tables. Skardi does
not parse or store graphs — the graph engine (Apache AGE: openCypher
inside Postgres) owns storage and traversal; Skardi forwards **read-only**
Cypher and maps results into Arrow rows with a planning-time-stable
schema. Design: `docs/superpowers/specs/2026-08-08-graph-engine-bypass-design.md`
in the [skardi repo](https://github.com/SkardiLabs/skardi); operational truth:
[`docs/graph.md`](https://github.com/SkardiLabs/skardi/blob/main/docs/graph.md)
there. When this skill and those documents
disagree, the documents win — check them, then fix this skill.

**Version prerequisite:** Skardi v0.6.0 or later, the first release with
`type: graph` sources and the `cypher_query` / `graph_schema` UDTFs; v0.5.0
has neither. This skill was verified against commit
[`1f2ecae`](https://github.com/SkardiLabs/skardi/commit/1f2ecae0f95b0a01232fadb815eae1c1c86efc48),
which v0.6.0 contains. The backend is
AGE (milestone status M4 — YAML catalog views and pipeline parameter
passthrough). Neo4j and Kuzu are later milestones: the config carries a
`backend:` field for them, but do not write configuration or guidance for a
backend that has no implementation. Milestone one is read-only end to end;
write paths are deferred by design.

The reason this skill exists: every trap below is real, was hit, and is
documented — but scattered. The two that cost the most debugging time:
**the ad-hoc `columns` argument binds positionally** (two same-typed
columns declared out of RETURN order swap silently — no error, wrong
data), and **a view's SQL `WHERE` does not push into its Cypher** (a
query that wants one row still fails `RowCapExceeded` if the view is
unbounded). Both are invisible until they bite.

## The workflow

Work the phases in order. Each phase names its reference file — read it
before doing that phase's work, not after it goes wrong.

### Phase 1 — Provision the backend

Read [references/provisioning.md](references/provisioning.md).

Stand up (or locate) the AGE instance and create a **least-privilege
reader role** — never a superuser, and never "fix" a failing
registration by upgrading the credential. Credentials enter Skardi as
environment-variable NAMES only; a password embedded in
`connection_string` is rejected at config load.

### Phase 2 — Declare the source

Read [references/configuration.md](references/configuration.md).

Write the `type: graph` entry in context YAML: `hierarchy_level:
catalog` (required — views register as `<name>.main.<view>`), the
`graph:` block (backend, graph_name, credential env-var names, bounds),
and the views. Decide view vs ad-hoc deliberately:

- **Declare a view** when agents need a predictable table name and the
  query shape is stable. A view's Cypher **must carry its own bound**
  (`WHERE` / `LIMIT` inside the Cypher) — SQL predicates over the view
  do not push down.
- **Leave it to ad-hoc `cypher_query`** when the predicate belongs to
  the caller. The caller places the bound where it works.

### Phase 3 — Verify registration

Read the registration-semantics section of
[references/configuration.md](references/configuration.md), then start
the server and check which of the three states you got:

- **healthy** — backend reachable, every view validated with one live
  call. Note what that proves: arity always; type and `nullable: false`
  only for the sampled row. Per-row enforcement lives in execution.
- **refused** (server does not start) — the backend ANSWERED and a view's
  contract is broken (RETURN arity/types disagree with the declared
  schema), or the server answered with an error (bad credentials, AGE
  absent, graph missing). This is a bug in your declaration or
  deployment, not an outage — fix it, don't retry it.
- **degraded** — genuine connectivity failure only (DNS, refused dial,
  network timeout). Views still register on declared schemas; the first
  scan retries; recovery flips healthy on ANY server response.

Then prove the read path with the discovery UDTF and one view scan:

```sql
SELECT * FROM graph_schema('kg');          -- one (label, kind) row per label
SELECT * FROM kg.main.people LIMIT 5;
```

### Phase 4 — Write the queries

Read [references/querying.md](references/querying.md) — it carries the
positional-binding rule, the getter table, and the patterns. The three
rules that prevent silent wrong answers:

1. **`columns` is positional.** Declare ad-hoc columns in RETURN order;
   the names are labels for SQL, not a lookup key.
2. **Properties are JSON text; pick the getter by the stored JSON
   type.** `json_get_str` on a numeric property returns NULL — not an
   error, not a coercion. `age` needs `json_get_int`.
3. **`->` / `->>` / `?` are deliberately not installed** (the rewrite
   would break federated pushdown session-wide). Use the getter UDFs.

### Phase 5 — Pipeline it (when a pipeline is asked for)

Read the pipelines section of
[references/querying.md](references/querying.md). One spelling works:
the `{param}` placeholder occupies the **whole `params` argument** of
`cypher_query`, and the caller passes the params JSON **as a string**.
Connection, cypher, and columns stay strict literals — they determine
the plan, so a placeholder cannot produce one.

### When something breaks

Read [references/troubleshooting.md](references/troubleshooting.md) —
symptom → diagnosis, including how graph health surfaces through
`GET /data_source` (and what the skardi-cloud gateway's projection
deliberately hides from tenants).

## Working style

- **Verify against the running system, not this skill.** One
  `graph_schema('kg')` call answers more than an hour of config
  re-reading. The milestone status and bounds cited here were true when
  written; the skardi repo's `docs/graph.md` and its config code are the
  authority.
- **No credentials anywhere but env-var names.** Not in YAML, not in
  logs, not in error reports you paste. Connection strings are never
  echoed — they may carry credentials on other deployments even though
  this one must not.
- **Errors are typed and name their cause.** If you see an untyped or
  misleading graph error, that's a bug worth filing, not working around.
- **Don't widen bounds to make symptoms disappear.** `max_rows` and
  `query_timeout_seconds` are protections; the fix for `RowCapExceeded`
  is a bound in the view's Cypher, and the fix for a timeout is usually
  a narrower traversal.
Pliki w paczce (5)
  • SKILL.md 7 KB
  • references/configuration.md 7 KB
  • references/provisioning.md 3 KB
  • references/querying.md 5 KB
  • references/troubleshooting.md 5 KB

Wersje

W bazie nie ma innych skilli o nazwie graph-source.

Migawka bazy z 13.11.2026 · wersja paczki 9836a8d2d0b9 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 82graph-rag
    Odpowiada na pytania o graf wiedzy z serwera skardi, także w Postgres z Apache AGE, przechodząc po powiązaniach lub szukając encji.
  • 100skardi-query-log
    Sprawdza przed wysłaniem zapytania SQL do Skardi, czy takie pytanie już zadano, i wykorzystuje wcześniej działający kod.
  • 100neo4j-graph-cypher-queries
    Pomaga modelować gęste sieci powiązań i pisać przejścia po grafie w języku Cypher dla bazy Neo4j.
  • 100relate
    Pomaga pisać w JavaScript i TypeScript kod, który tworzy, zapytuje i osadza lokalną bazę grafową w Cypher.
  • 100relate
    Pomaga pisać w Pythonie kod, który tworzy, zapytuje i osadza lokalną bazę grafową Relate w Cypher.
  • 100graphrag-patterns
    Wdraża GraphRAG, łączący graf wiedzy z RAG, by odpowiadać na pytania wieloetapowe i łączyć encje między dokumentami.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.