Skip to main content

Interface: IGraphDatabase

Defined in: src/types/interfaces/graph.interface.ts:353

Graph database interface for Neo4j.

Remarks​

Provides access to Chive's knowledge graph for field relationships, authority control, and faceted classification.

Implementation notes:

  • Uses Neo4j 5+ with Cypher queries
  • Field nodes use hierarchical labels
  • Relationships are typed and weighted
  • Authority records stored in dedicated collection

Methods​

aggregateFacetRefinements()​

aggregateFacetRefinements(currentFacets): Promise<{ energy: readonly object[]; matter: readonly object[]; personality: readonly object[]; space: readonly object[]; time: readonly object[]; }>

Defined in: src/types/interfaces/graph.interface.ts:600

Aggregates available facet values with counts for refinement UI.

Parameters​

currentFacets​

readonly Facet[]

Currently selected facets to filter by

Returns​

Promise<{ energy: readonly object[]; matter: readonly object[]; personality: readonly object[]; space: readonly object[]; time: readonly object[]; }>

Available facet values with preprint counts per dimension

Remarks​

Returns only facet values that would produce results given current filters. Counts represent how many preprints match if that facet is added.

Example​

const refinements = await graphDb.aggregateFacetRefinements([
  { dimension: 'personality', value: 'Computer Science' }
]);
// Returns available matter, energy, space, time values

createAuthorityRecord()​

createAuthorityRecord(record): Promise<void>

Defined in: src/types/interfaces/graph.interface.ts:466

Creates an authority record.

Parameters​

record​

AuthorityRecord

Authority record data

Returns​

Promise<void>

Promise resolving when created

Remarks​

Stores authority record in graph for linking to field nodes and facets.

Example​

await graphDb.createAuthorityRecord({
  id: 'neural-networks-cs',
  authorizedHeading: 'Neural networks (Computer science)',
  alternateHeadings: ['Neural nets', 'ANNs', 'Artificial neural networks'],
  scope: 'For biological networks, see Nervous system',
  source: 'wikidata',
  wikidataId: 'Q43479'
});

createRelationship()​

createRelationship(relationship): Promise<void>

Defined in: src/types/interfaces/graph.interface.ts:420

Creates a relationship between field nodes.

Parameters​

relationship​

FieldRelationship

Relationship data

Returns​

Promise<void>

Promise resolving when created

Remarks​

Creates a directed relationship edge in the graph.

Example​

await graphDb.createRelationship({
  fromId: 'neural-networks',
  toId: 'artificial-intelligence',
  type: 'narrower',
  strength: 0.95
});

createVote()​

createVote(vote): Promise<void>

Defined in: src/types/interfaces/graph.interface.ts:541

Creates a vote record for a proposal.

Parameters​

vote​

VoteRecord

Vote record data

Returns​

Promise<void>

Promise resolving when created

Remarks​

Persists vote to graph database and updates proposal vote counts. Votes are weighted by voter role:

  • community-member: 1.0x
  • reviewer: 2.0x
  • domain-expert: 3.0x
  • administrator: 5.0x

Example​

await graphDb.createVote({
  uri: 'at://did:plc:voter/pub.chive.graph.vote/abc123',
  proposalUri: 'at://did:plc:author/pub.chive.graph.fieldProposal/xyz',
  voterDid: 'did:plc:voter',
  voterRole: 'reviewer',
  vote: 'approve',
  rationale: 'Well-structured proposal with clear scope',
  createdAt: new Date()
});

findRelatedFields()​

findRelatedFields(fieldId, maxDepth?): Promise<readonly FieldNode[]>

Defined in: src/types/interfaces/graph.interface.ts:441

Finds related fields by traversing relationships.

Parameters​

fieldId​

string

Starting field ID

maxDepth?​

number

Maximum traversal depth

Returns​

Promise<readonly FieldNode[]>

Related field nodes

Remarks​

Uses graph traversal to find related fields up to maxDepth hops away. Useful for "explore related fields" features.

Example​

const related = await graphDb.findRelatedFields('neural-networks', 2);
// Returns fields within 2 hops: AI, deep learning, machine learning, etc.

getCommunityProposals()​

getCommunityProposals(fieldId): Promise<readonly FieldProposal[]>

Defined in: src/types/interfaces/graph.interface.ts:510

Gets pending community proposals for a field.

Parameters​

fieldId​

string

Field ID

Returns​

Promise<readonly FieldProposal[]>

Pending proposals

Remarks​

Returns proposals awaiting community review for this field.

Example​

const proposals = await graphDb.getCommunityProposals('neural-networks');
proposals.forEach(p => {
  console.log(`${p.proposalType}: ${p.rationale}`);
});

getFieldById()​

getFieldById(fieldId): Promise<null | FieldNode>

Defined in: src/types/interfaces/graph.interface.ts:397

Gets a field node by ID.

Parameters​

fieldId​

string

Field identifier

Returns​

Promise<null | FieldNode>

Field node or null if not found

Remarks​

Retrieves a single field node by its unique identifier.

Example​

const field = await graphDb.getFieldById('quantum-computing');
if (field) {
  console.log(`Found: ${field.label}`);
}

getProposalById()​

getProposalById(proposalId): Promise<null | FieldProposal>

Defined in: src/types/interfaces/graph.interface.ts:685

Gets a proposal by ID.

Parameters​

proposalId​

string

Proposal identifier

Returns​

Promise<null | FieldProposal>

Proposal if found, null otherwise

Example​

const proposal = await graphDb.getProposalById('abc123');

getProposals()​

getProposals(filters): Promise<{ hasMore: boolean; offset: number; proposals: readonly FieldProposal[]; total: number; }>

Defined in: src/types/interfaces/graph.interface.ts:656

Lists proposals with optional filtering.

Parameters​

filters​

Proposal filters (status, type, proposer, etc.)

createdAfter​

Date

createdBefore​

Date

fieldUri​

string

limit​

number

offset​

number

proposalType​

readonly ("create" | "update" | "delete" | "merge")[]

proposerDid​

DID

status​

readonly ("pending" | "approved" | "rejected")[]

Returns​

Promise<{ hasMore: boolean; offset: number; proposals: readonly FieldProposal[]; total: number; }>

Paginated proposals

Example​

const result = await graphDb.getProposals({
  status: ['pending'],
  limit: 20
});

getVotesForProposal()​

getVotesForProposal(proposalUri): Promise<readonly VoteRecord[]>

Defined in: src/types/interfaces/graph.interface.ts:700

Gets votes for a specific proposal.

Parameters​

proposalUri​

string

Proposal AT-URI

Returns​

Promise<readonly VoteRecord[]>

Votes cast on the proposal

Example​

const votes = await graphDb.getVotesForProposal('at://did:plc:xxx/pub.chive.graph.fieldProposal/abc');

listFields()​

listFields(options): Promise<{ cursor: string; fields: readonly FieldNode[]; hasMore: boolean; total: number; }>

Defined in: src/types/interfaces/graph.interface.ts:628

Lists field nodes with optional filtering and pagination.

Parameters​

options​

List options (status filter, parent filter, pagination)

cursor​

string

limit​

number

parentId​

string

status​

"approved" | "proposed" | "under_review" | "deprecated"

Returns​

Promise<{ cursor: string; fields: readonly FieldNode[]; hasMore: boolean; total: number; }>

Field nodes with pagination info

Remarks​

Returns field nodes matching the specified filters.

Example​

const fields = await graphDb.listFields({
  status: 'approved',
  limit: 50,
  cursor: '50'
});

queryByFacets()​

queryByFacets(facets): Promise<readonly string[]>

Defined in: src/types/interfaces/graph.interface.ts:489

Queries field nodes by facets.

Parameters​

facets​

readonly Facet[]

Facet filters

Returns​

Promise<readonly string[]>

Matching field IDs

Remarks​

Finds fields that match all specified facets (AND query). Use for faceted navigation and filtering.

Example​

const fields = await graphDb.queryByFacets([
  { dimension: 'matter', value: 'Proteins' },
  { dimension: 'energy', value: 'Meta-analysis' }
]);
// Returns fields about protein meta-analyses

searchAuthorityRecords()​

searchAuthorityRecords(query, options?): Promise<{ hasMore: boolean; records: readonly AuthorityRecord[]; total: number; }>

Defined in: src/types/interfaces/graph.interface.ts:566

Searches authority records by query text, type, and status.

Parameters​

query​

string

Search query text (matches authorized heading and alternates)

options?​

Search options (type filter, status filter, pagination)

limit​

number

offset​

number

status​

"approved" | "proposed" | "under_review" | "deprecated"

type​

"person" | "organization" | "concept" | "place"

Returns​

Promise<{ hasMore: boolean; records: readonly AuthorityRecord[]; total: number; }>

Matching authority records with pagination info

Remarks​

Uses Neo4j fulltext search index for efficient matching. Supports filtering by authority type and approval status.

Example​

const results = await graphDb.searchAuthorityRecords('neural network', {
  type: 'concept',
  status: 'approved',
  limit: 20,
  offset: 0
});

upsertField()​

upsertField(field): Promise<void>

Defined in: src/types/interfaces/graph.interface.ts:376

Creates or updates a field node.

Parameters​

field​

FieldNode

Field node data

Returns​

Promise<void>

Promise resolving when upserted

Remarks​

Upserts the field node (insert or update based on ID).

Example​

await graphDb.upsertField({
  id: 'quantum-computing',
  label: 'Quantum Computing',
  type: 'field',
  description: 'Computing using quantum mechanics principles',
  wikidataId: 'Q484761'
});