find()

Search your knowledge graph using Triple Intelligence: vector search, graph relationships, and metadata filtering.

Signature

brain.find(options: FindOptions): Promise<Entity[]>

Parameters

Property Type Description
query string Semantic search query (vector search)
where object Metadata filter with readable operators
connected object Graph relationship filter
nounType NounType | NounType[] Filter by entity type
limit number Maximum results (default: 10)
threshold number Minimum similarity score (0-1)

Returns

A Promise that resolves to an array of matching entities with similarity scores.

Examples

Vector Search

vector-search.js
// Find by semantic meaning
const results = await brain.find({
  query: "programming languages for web development"
})

// Results include similarity scores
results.forEach(r => {
  console.log(r.data, r.score)
})
// "JavaScript is a programming language" 0.92
// "TypeScript adds static types" 0.88

Metadata Filtering

Brainy uses readable, human-friendly operators instead of cryptic symbols:

metadata-filter.js
// Exact match (implicit default)
const results = await brain.find({
  where: {
    category: "language"  // equals is implicit
  }
})

// Explicit equals
const exact = await brain.find({
  where: {
    status: { equals: "published" }
  }
})

// Range operators
const recent = await brain.find({
  where: {
    year: { greaterThanOrEqual: 2020 },
    views: { greaterThan: 1000 }
  }
})

// Multiple values
const featured = await brain.find({
  where: {
    status: { oneOf: ["published", "featured"] }
  }
})

Combining Filters

combined-filters.js
// Complex filtering with multiple operators
const results = await brain.find({
  query: "machine learning",
  where: {
    year: { between: [2020, 2024] },
    rating: { greaterThanOrEqual: 4.5 },
    category: { oneOf: ["research", "tutorial"] },
    deprecated: { notEquals: true }
  }
})

// Check if field exists
const withTags = await brain.find({
  where: {
    tags: { exists: true }
  }
})

// Array contains
const tagged = await brain.find({
  where: {
    tags: { contains: "typescript" }
  }
})

Logical Operators

logical-operators.js
// OR logic: match any condition
const results = await brain.find({
  where: {
    anyOf: [
      { category: "frontend" },
      { category: "fullstack" }
    ]
  }
})

// AND logic: match all conditions
const strict = await brain.find({
  where: {
    allOf: [
      { year: { greaterThan: 2020 } },
      { status: "published" }
    ]
  }
})

// NOT logic: negate condition
const notDraft = await brain.find({
  where: {
    not: { status: "draft" }
  }
})

Graph Relationships

graph-query.js
// Find entities connected TO a specific entity
const extensions = await brain.find({
  connected: {
    to: javascriptId,
    type: "extends"
  }
})

// Find entities connected FROM a specific entity
const creations = await brain.find({
  connected: {
    from: authorId,
    type: "creates"
  }
})

// Find any connection
const related = await brain.find({
  connected: { to: entityId }
})

Triple Intelligence (All Three)

triple-query.js
// Combine all three query types
const results = await brain.find({
  // Vector: semantic search
  query: "machine learning algorithms",

  // Metadata: structured filtering
  where: {
    year: { greaterThanOrEqual: 2020 },
    category: "research"
  },

  // Graph: relationship constraints
  connected: {
    to: neuralNetworksId,
    type: "references"
  },

  // Limit results
  limit: 5
})

Filter by Noun Type

noun-type-filter.js
import { NounType } from '@soulcraft/brainy'

// Find only People
const people = await brain.find({
  query: "technology leaders",
  nounType: NounType.Person
})

// Find multiple types
const mixed = await brain.find({
  query: "San Francisco tech",
  nounType: [NounType.Person, NounType.Location]
})

Pagination

pagination.js
// Get first page
const page1 = await brain.find({
  query: "programming",
  limit: 10
})

// Get next page using the last item's score
const page2 = await brain.find({
  query: "programming",
  limit: 10,
  threshold: page1[page1.length - 1].score - 0.001
})

Supported Operators

Brainy uses readable, English operators that are easy to understand and remember:

Comparison Operators

Operator Aliases Description
equals is, eq Exact match (implicit default)
notEquals isNot, ne Not equal to value
greaterThan gt Greater than value
greaterThanOrEqual greaterEqual, gte Greater than or equal
lessThan lt Less than value
lessThanOrEqual lessEqual, lte Less than or equal
between - Value within range [min, max]

Collection Operators

Operator Aliases Description
oneOf in Value matches any in array
contains - Array field contains value
exists - Field exists (true/false)

Logical Operators

Operator Description
allOf All conditions must match (AND)
anyOf Any condition can match (OR)
not Negate condition (NOT)

See Also

Next: relate() →