docs(8.0): correct public docs to the real 8.0 API + honest perf claims
The GA-readiness audit found the public docs had drifted from the shipped surface and presented uncited performance numbers as measured fact. - quick-start: `FindResult`→`Result`, `VerbType.BuiltOn`→`DependsOn` (the canonical getting-started example now compiles). - noun-verb-taxonomy: rewrote every sample off removed/fictional APIs (`augment`/`connectModel`/`getVerbs`/two-arg `add`/`like`/`$gte`) onto the real single-object `add`/`find`/`relate`/`related`; replaced the stale 31-noun/40-verb catalogs with accurate, complete tables (42 nouns, 127 verbs). - triple-intelligence: `like:`→`query:`, dollar-operators→bare operators, and several other fictional keys swept to the real `FindParams`. - FIND_SYSTEM / PERFORMANCE / index-architecture / BATCHING: replaced fabricated, mutually-inconsistent latency tables and uncited speedup multipliers with Big-O characterizations, qualitative mechanism descriptions, and the one genuinely-measured benchmark (graph O(1) neighbor lookup), per the evidence-based-claims rule. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
3d116190f3
commit
40d2cd5419
9 changed files with 1209 additions and 2283 deletions
|
|
@ -23,29 +23,37 @@ Traditional databases force you to choose between vector search, graph traversal
|
|||
|
||||
### Unified Query Structure
|
||||
|
||||
`find()` accepts a single `FindParams` object (or a natural-language string). One
|
||||
object combines all three intelligences:
|
||||
|
||||
```typescript
|
||||
interface TripleQuery {
|
||||
// Vector/Semantic search
|
||||
like?: string | Vector | any
|
||||
similar?: string | Vector | any
|
||||
|
||||
// Graph/Relationship search
|
||||
interface FindParams {
|
||||
// Vector intelligence — semantic similarity
|
||||
query?: string // Natural-language / semantic query (embedded, matched via HNSW + text index)
|
||||
vector?: number[] // Pre-computed embedding for direct vector search
|
||||
|
||||
// Metadata intelligence — structured field filters
|
||||
type?: NounType | NounType[] // Filter by entity type
|
||||
subtype?: string | string[] // Filter by per-product subtype
|
||||
where?: Record<string, any> // Field predicates with bare operators (gte, lt, in, contains, exists…)
|
||||
|
||||
// Graph intelligence — relationship traversal
|
||||
connected?: {
|
||||
to?: string | string[]
|
||||
from?: string | string[]
|
||||
type?: string | string[]
|
||||
depth?: number
|
||||
to?: string // Reachable to this entity
|
||||
from?: string // Reachable from this entity
|
||||
via?: VerbType | VerbType[] // Relationship type(s) to traverse (alias: type)
|
||||
depth?: number // Max traversal depth (default: 1)
|
||||
direction?: 'in' | 'out' | 'both'
|
||||
}
|
||||
|
||||
// Field/Attribute search
|
||||
where?: Record<string, any>
|
||||
|
||||
// Advanced options
|
||||
limit?: number
|
||||
boost?: 'recent' | 'popular' | 'verified' | string
|
||||
explain?: boolean
|
||||
threshold?: number
|
||||
|
||||
// Proximity — nearest neighbours of a known entity
|
||||
near?: { id: string; threshold?: number }
|
||||
|
||||
// Control
|
||||
limit?: number // Max results (default: 10)
|
||||
offset?: number // Skip N results
|
||||
orderBy?: string // Field to sort by (e.g. 'createdAt')
|
||||
order?: 'asc' | 'desc' // Sort direction
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -74,10 +82,10 @@ const results = await brain.find("machine learning concepts")
|
|||
#### Combined Intelligence Query
|
||||
```typescript
|
||||
const results = await brain.find({
|
||||
like: "neural networks",
|
||||
query: "neural networks",
|
||||
where: {
|
||||
category: "research",
|
||||
year: { $gte: 2023 }
|
||||
year: { gte: 2023 }
|
||||
},
|
||||
connected: {
|
||||
to: "deep-learning-team",
|
||||
|
|
@ -109,8 +117,8 @@ All three search types execute simultaneously:
|
|||
```typescript
|
||||
// Parallel execution for balanced query
|
||||
const results = await brain.find({
|
||||
like: "AI research", // ~1000 potential matches
|
||||
where: { type: "paper" }, // ~500 potential matches
|
||||
query: "AI research", // ~1000 potential matches
|
||||
where: { kind: "paper" }, // ~500 potential matches
|
||||
connected: { to: "stanford" } // ~200 potential matches
|
||||
})
|
||||
// All three execute in parallel, results fused
|
||||
|
|
@ -126,7 +134,7 @@ Operations chain for maximum efficiency:
|
|||
// Progressive execution for selective query
|
||||
const results = await brain.find({
|
||||
where: { userId: "user123" }, // Very selective (1-10 matches)
|
||||
like: "recent posts", // Applied to filtered set
|
||||
query: "recent posts", // Applied to filtered set
|
||||
limit: 5
|
||||
})
|
||||
// Metadata filter first, then vector search on results
|
||||
|
|
@ -166,10 +174,10 @@ const results = await brain.find(
|
|||
)
|
||||
// Automatically converts to:
|
||||
// {
|
||||
// like: "AI papers",
|
||||
// where: {
|
||||
// query: "AI papers",
|
||||
// where: {
|
||||
// institution: "Stanford",
|
||||
// published: { $gte: "2024-01-01" }
|
||||
// published: { gte: "2024-01-01" }
|
||||
// }
|
||||
// }
|
||||
```
|
||||
|
|
@ -188,10 +196,10 @@ The NLP processor identifies query intent:
|
|||
|
||||
Successful execution plans are cached:
|
||||
```typescript
|
||||
// First query: 50ms (plan generation + execution)
|
||||
// First call parses the natural-language query and builds an execution plan
|
||||
await brain.find("machine learning papers")
|
||||
|
||||
// Subsequent similar queries: 10ms (cached plan)
|
||||
// A structurally similar query reuses that plan, skipping plan generation
|
||||
await brain.find("deep learning papers")
|
||||
```
|
||||
|
||||
|
|
@ -213,50 +221,45 @@ Triple Intelligence leverages all available indexes:
|
|||
|
||||
### Explain Mode
|
||||
|
||||
Understand how your query was executed:
|
||||
Diagnose how a query's `where` fields map to the index. Run `brain.explain()`
|
||||
first whenever `find()` returns surprising or empty results:
|
||||
|
||||
```typescript
|
||||
const results = await brain.find({
|
||||
like: "quantum computing",
|
||||
where: { category: "research" },
|
||||
explain: true
|
||||
const plan = await brain.explain({
|
||||
query: "quantum computing",
|
||||
where: { category: "research" }
|
||||
})
|
||||
|
||||
console.log(results[0].explanation)
|
||||
// {
|
||||
// plan: "field-first-progressive",
|
||||
// timing: {
|
||||
// fieldFilter: 2,
|
||||
// vectorSearch: 8,
|
||||
// fusion: 1
|
||||
// },
|
||||
// selectivity: {
|
||||
// field: 0.1,
|
||||
// vector: 0.3
|
||||
// }
|
||||
// }
|
||||
console.log(plan.fieldPlan)
|
||||
// [
|
||||
// { field: 'category', path: 'column-store', notes: '...' }
|
||||
// ]
|
||||
|
||||
console.log(plan.warnings)
|
||||
// e.g. ['Field "category" has no index entries. find() will return [] silently...']
|
||||
```
|
||||
|
||||
### Boosting
|
||||
### Result Ordering
|
||||
|
||||
Apply custom ranking boosts:
|
||||
Sort results by any stored field with `orderBy` / `order`:
|
||||
|
||||
```typescript
|
||||
const results = await brain.find({
|
||||
like: "news articles",
|
||||
boost: 'recent', // Boost recent items
|
||||
where: { verified: true }
|
||||
query: "news articles",
|
||||
where: { verified: true },
|
||||
orderBy: 'createdAt', // Newest first
|
||||
order: 'desc'
|
||||
})
|
||||
```
|
||||
|
||||
### Threshold Control
|
||||
### Similarity Threshold
|
||||
|
||||
Set minimum similarity thresholds:
|
||||
Find the nearest neighbours of a known entity and keep only close matches with
|
||||
`near`:
|
||||
|
||||
```typescript
|
||||
const results = await brain.find({
|
||||
like: "exact match needed",
|
||||
threshold: 0.9, // Only very similar results
|
||||
near: { id: anchorId, threshold: 0.9 }, // Only results >= 0.9 similarity
|
||||
limit: 10
|
||||
})
|
||||
```
|
||||
|
|
@ -283,8 +286,8 @@ const results = await brain.find({
|
|||
```typescript
|
||||
// Find similar content with constraints
|
||||
const results = await brain.find({
|
||||
like: query,
|
||||
where: {
|
||||
query: searchText,
|
||||
where: {
|
||||
status: 'published',
|
||||
language: 'en'
|
||||
}
|
||||
|
|
@ -295,10 +298,10 @@ const results = await brain.find({
|
|||
```typescript
|
||||
// Find items related to a specific item
|
||||
const results = await brain.find({
|
||||
connected: {
|
||||
connected: {
|
||||
to: itemId,
|
||||
depth: 2,
|
||||
type: 'similar'
|
||||
via: VerbType.RelatedTo
|
||||
},
|
||||
limit: 20
|
||||
})
|
||||
|
|
@ -309,10 +312,11 @@ const results = await brain.find({
|
|||
// Recent items matching criteria
|
||||
const results = await brain.find({
|
||||
where: {
|
||||
timestamp: { $gte: Date.now() - 86400000 }
|
||||
timestamp: { gte: Date.now() - 86400000 }
|
||||
},
|
||||
like: "trending topics",
|
||||
boost: 'recent'
|
||||
query: "trending topics",
|
||||
orderBy: 'timestamp',
|
||||
order: 'desc'
|
||||
})
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue