Querying Data

The Query client provides multiple ways to search and validate data in the knowledge base, from simple sort-based lookups to full structured search with partial matching.

Query by sort

Find all terms belonging to a specific sort. By default, terms of subsorts (subtypes) are included.

import { ReasoningLayerClient } from '@kortexya/reasoninglayer';

const client = new ReasoningLayerClient({
  baseUrl: 'https://platform.ovh.reasoninglayer.ai',
  tenantId: 'my-tenant-uuid',
  auth: { mode: 'cookie' },
});

// Find all persons (including employees, students, etc.)
const persons = await client.query.findBySort({
  sortId: personSortId,
});

for (const term of persons) {
  console.log(`${term.id}: sort=${term.sortId}`);
  console.log('  features:', term.features);
}

Use the optional filter parameter for feature-based filtering:

// Filter by a specific feature value
const activePeople = await client.query.findBySort({
  sortId: personSortId,
  filter: { status: 'active' },
});

Query unifiable

Find terms that unify with a given pattern. This uses the inference engine’s unification algorithm to match terms structurally.

// Find all persons named "Alice"
const matches = await client.query.findUnifiable({
  pattern: {
    sortId: personSortId,
    features: {
      name: 'Alice',
    },
  },
  maxResults: 10,
});

for (const term of matches) {
  console.log(`Found: ${term.id}`);
  console.log(`  features:`, term.features);
}

Use variables to leave parts of the pattern open:

// Find all persons with any name (variable matches anything)
const allPersons = await client.query.findUnifiable({
  pattern: {
    sortId: personSortId,
    features: {
      name: '?Name',
      age: 30,
    },
  },
});

Convenience aliases

osfSearch is also available as search, and findUnifiable is also available as findMatching, for developers who prefer more descriptive method names.

Structured search

The structured search endpoint supports the full power of the query language, including entity matching, relation discovery, and partial matching when the query is too vague.

const result = await client.query.search({
  pattern: {
    sortId: personSortId,
    features: {
      age: 30,
    },
  },
  maxEntities: 20,
  minMatchDegree: 0.5,
  enableUnification: true,
});

// Matched entities
for (const entity of result.entities) {
  console.log(`${entity.name ?? entity.termId} (degree: ${entity.matchDegree})`);
  console.log(`  sort: ${entity.sortId}`);
  console.log(`  features:`, entity.features);
  if (entity.matchReason) {
    console.log(`  reason: ${entity.matchReason}`);
  }
}

// Discovered relations between entities
for (const rel of result.relations) {
  console.log(`${rel.sourceSort} --${rel.relationName}--> ${rel.targetSort}`);
  console.log(`  cardinality: ${rel.cardinality}, confidence: ${rel.confidence}`);
}

// Statistics
console.log(`Matched: ${result.stats.entitiesMatched}`);
console.log(`Relations: ${result.stats.relationsDiscovered}`);
console.log(`Duration: ${result.stats.durationUs}us`);

Note

search is an alias for the original method osfSearch. Both are equivalent.

Handling suspended queries

When a query is too vague, the response includes a suspended field with information about what is missing and how to refine the query.

const result = await client.query.search({
  pattern: {
    sortId: sortId,
    features: {},
  },
});

if (result.suspended) {
  console.log(`Partial confidence: ${result.suspended.confidence}`);

  for (const info of result.suspended.missingInfo) {
    console.log(`Missing: ${info.description} (priority: ${info.priority})`);
  }

  for (const option of result.suspended.resumptionOptions) {
    console.log(`Suggestion: ${option.description}`);
    console.log(`  Expected gain: ${option.expectedConfidenceGain}`);
  }
}

Filtering by collection or namespace

const result = await client.query.search({
  pattern: {
    sortId: sortId,
    features: { status: 'active' },
  },
  collectionId: 'collection-uuid',
  namespaceId: 'namespace-uuid',
  maxEntities: 100,
});

Natural language query

Query the knowledge base using natural language. The engine translates your question into a structured query.

const result = await client.query.nlQuery({
  query: 'Find all employees older than 30 in the engineering department',
  mode: 'llm',
  tenantId: 'my-tenant-uuid',
});

if (result.success) {
  for (const item of result.results) {
    console.log(`${item.sortName}: ${item.id}`);
    console.log('  features:', item.features);
  }

  if (result.explanation) {
    console.log(`Explanation: ${result.explanation}`);
  }
  if (result.generatedOsf) {
    console.log(`Generated query: ${result.generatedOsf}`);
  }
} else {
  console.error(`Query failed: ${result.error}`);
}

Three query modes are available:

Mode	Description
llm	LLM-powered translation to structured query (default)
constraint	Tool-call based translation with structured output
cognitive	Agent-powered query with session continuity

// Constraint mode returns tool call info
const constrained = await client.query.nlQuery({
  query: 'Show me active sensors',
  mode: 'constraint',
  tenantId: 'my-tenant-uuid',
});
if (constrained.toolCall) {
  console.log(`Tool: ${constrained.toolCall.name}`);
  console.log(`Confidence: ${constrained.toolCall.confidence}`);
}

// Cognitive mode supports session continuity
const cognitive = await client.query.nlQuery({
  query: 'What about their temperatures?',
  mode: 'cognitive',
  tenantId: 'my-tenant-uuid',
  sessionId: 'session-uuid', // continue from previous query
});
if (cognitive.cognitiveSummary) {
  console.log(cognitive.cognitiveSummary);
}

Validate term

Check whether a term satisfies its sort’s type witnesses without creating or modifying it.

const validation = await client.query.validateTerm({
  term: {
    sortId: sortId,
    features: {
      name: 'Alice',
      age: 30,
    },
  },
});

console.log(`Valid: ${validation.valid}`);

if (!validation.valid) {
  console.log(`Reason: ${validation.failureReason}`);
}

// Witness details
for (const w of validation.witnessesSatisfied) {
  console.log(`Satisfied: ${w.witnessId} (confidence: ${w.confidence})`);
}
for (const w of validation.witnessesResiduated) {
  console.log(`Residuated: ${w.witnessId} (trigger: ${w.trigger})`);
}

Validate unify

Check whether two terms can be unified and validate the result against type witnesses.

const result = await client.query.validatedUnify({
  term1: { sortId: sortIdA, features: { name: 'Alice' } },
  term2: { sortId: sortIdB, features: { name: 'Bob' } },
});

if (result.success) {
  console.log(`Unified term:`, result.unifiedTerm);
  console.log(`GLB sort: ${result.glbSortId}`);
  console.log(`Duration: ${result.durationUs}us`);
} else {
  console.log(`Unification failed: ${result.failureReason}`);
}

// Witness validation of the unified result
for (const w of result.witnessesSatisfied) {
  console.log(`Witness ${w.witnessId}: satisfied`);
}
for (const w of result.witnessesResiduated) {
  console.log(`Witness ${w.witnessId}: residuated (${w.trigger})`);
}