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,
    },
  },
});

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.sourceId} --${rel.relationType}--> ${rel.targetId}`);
  console.log(`  method: ${rel.discoveryMethod}, confidence: ${rel.confidence}`);
}

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

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})`);
}