ebrains-kg-query

A JavaScript library for building and executing queries against the EBRAINS Knowledge Graph Core API v3.

Features

• Query builder — construct KG query documents (JSON-LD) using a composable API
• Data fetching — retrieve single items or collections with automatic in-memory caching
• Result merging — merge results across KG stages (e.g. IN_PROGRESS + RELEASED) for complete data

Installation

npm install ebrains-kg-query

Usage

Building queries

import { buildKGQuery, simpleProperty as S, linkProperty as L, reverseLinkProperty as R } from "ebrains-kg-query";

const datasetQuery = buildKGQuery("DatasetVersion", [
  S("@id"),
  S("fullName"),
  S("description"),
  L("author", [S("givenName"), S("familyName")], { expectSingle: false }),
]);

Fetching data

import { createKGClient } from "ebrains-kg-query";

const { getKGData, getKGItem, count } = createKGClient({
  kgUrl: "https://core.kg.ebrains.eu/v3",
  defaultStage: "RELEASED",
});

// auth object must have a `token` property (Bearer token string)
// and optionally `isCurator` (boolean)
const datasets = await getKGData("my datasets", datasetQuery, auth);
const dataset = await getKGItem("my datasets", datasetQuery, instanceId, auth);

Passing stage as an array (e.g. ["IN_PROGRESS", "RELEASED"]) fetches from both stages in parallel and deep-merges the results, so that fields missing in one stage are filled from the other.

Utilities

import { uuidFromUri, mergeItems, isEmptyValue } from "ebrains-kg-query";

uuidFromUri("https://kg.ebrains.eu/api/instances/abc-123"); // "abc-123"

API

buildKGQuery(baseType, structure)

Returns a KG query document (JSON-LD object) targeting the given openMINDS type.

simpleProperty(name, options?)

Property for simple datatypes (strings, numbers, @id, @type). Supports /-separated paths for chained traversal.

linkProperty(name, structure, options?)

Property that traverses a forward link. Options: expectSingle (default true), filter, required, type.

reverseLinkProperty(forwardName, reverseName, structure, options?)

Property that traverses a reverse link.

createKGClient({ kgUrl, defaultStage? })

Returns { queryKG, getKGItem, getKGData, count } bound to the given endpoint and default stage, sharing an in-memory cache.

mergeItems(primary, fallback)

Deep-merges two KG result objects. Primary values win; empty primary fields are filled from the fallback.

License

Apache 2.0 — see LICENSE.