David Snelling
32f5ac6fee
Fixed bug where getMetadataBatch() was reading from wrong directory: - FileSystemStorage: Changed to use getNounMetadata() instead of getMetadata() - OPFSStorage: Changed to use getNounMetadata() instead of getMetadata() - MetadataIndex fallback: Fixed to use getNounMetadata() - Added getNounMetadata() to StorageAdapter interface This resolves 0% success rate during metadata index rebuild. Also added comprehensive API documentation for return values and data field behavior.
152 lines
3.6 KiB
Markdown
152 lines
3.6 KiB
Markdown
# Brainy API Return Values
|
|
|
|
## Core Operations
|
|
|
|
### `brain.add()` - Adding Entities
|
|
|
|
**Returns:** `Promise<string>` - The ID of the created entity
|
|
|
|
```typescript
|
|
// ✅ Correct usage - add() returns the ID string directly
|
|
const id = await brain.add({
|
|
type: 'document',
|
|
data: 'My document content'
|
|
})
|
|
|
|
console.log('Created entity with ID:', id)
|
|
|
|
// Use the ID to create relationships
|
|
await brain.relate({
|
|
from: id,
|
|
to: anotherId,
|
|
type: 'references'
|
|
})
|
|
```
|
|
|
|
```typescript
|
|
// ❌ Incorrect - trying to access .id property
|
|
const result = await brain.add({
|
|
type: 'document',
|
|
data: 'My content'
|
|
})
|
|
|
|
console.log(result.id) // ❌ undefined - result IS the ID, not an object!
|
|
```
|
|
|
|
### Getting the Full Entity
|
|
|
|
If you need the full entity object after creation, use `brain.get()`:
|
|
|
|
```typescript
|
|
// Add entity and get its ID
|
|
const id = await brain.add({
|
|
type: 'document',
|
|
data: 'My content',
|
|
metadata: { label: 'Important Doc' }
|
|
})
|
|
|
|
// Get the full entity
|
|
const entity = await brain.get(id)
|
|
console.log(entity.id) // The ID
|
|
console.log(entity.type) // 'document'
|
|
console.log(entity.data) // 'My content'
|
|
console.log(entity.metadata) // { label: 'Important Doc', ... }
|
|
console.log(entity.vector) // The embedding vector
|
|
console.log(entity.createdAt) // Timestamp
|
|
```
|
|
|
|
### `brain.find()` - Finding Entities
|
|
|
|
**Returns:** `Promise<Entity[]>` - Array of full entity objects
|
|
|
|
```typescript
|
|
const entities = await brain.find({
|
|
query: 'machine learning',
|
|
limit: 10
|
|
})
|
|
|
|
// Each entity has full information
|
|
for (const entity of entities) {
|
|
console.log(entity.id)
|
|
console.log(entity.type)
|
|
console.log(entity.data)
|
|
console.log(entity.metadata)
|
|
}
|
|
```
|
|
|
|
### `brain.relate()` - Creating Relationships
|
|
|
|
**Returns:** `Promise<string>` - The ID of the created relationship
|
|
|
|
```typescript
|
|
const relationId = await brain.relate({
|
|
from: entityId1,
|
|
to: entityId2,
|
|
type: 'references'
|
|
})
|
|
|
|
console.log('Created relationship with ID:', relationId)
|
|
```
|
|
|
|
## Data Field Behavior
|
|
|
|
### String Data - Used for Embeddings
|
|
|
|
When `data` is a string, it's used to generate embeddings for semantic search:
|
|
|
|
```typescript
|
|
await brain.add({
|
|
type: 'document',
|
|
data: 'This text will be converted to an embedding vector',
|
|
metadata: {
|
|
title: 'My Document',
|
|
year: 2024
|
|
}
|
|
})
|
|
```
|
|
|
|
### Object Data - Structured Information
|
|
|
|
When `data` is an object, it's treated as structured data:
|
|
|
|
```typescript
|
|
await brain.add({
|
|
type: 'product',
|
|
data: {
|
|
name: 'Widget',
|
|
price: 29.99,
|
|
category: 'Tools'
|
|
},
|
|
vector: precomputedVector // Must provide vector when using object data
|
|
})
|
|
```
|
|
|
|
**Important:** If you provide object data without a `vector`, you must include a string somewhere for embedding generation, or the operation will fail.
|
|
|
|
### Metadata vs Data
|
|
|
|
- **`data`**: Primary content - used for embeddings (if string) or stored as structured data (if object)
|
|
- **`metadata`**: Auxiliary information - always stored as structured data, used for filtering
|
|
|
|
**Best practice for labels:**
|
|
```typescript
|
|
await brain.add({
|
|
type: 'document',
|
|
data: 'The full text content of the document...', // For semantic search
|
|
metadata: {
|
|
label: 'Quick Reference Label', // For display
|
|
author: 'John Doe',
|
|
category: 'Technical'
|
|
}
|
|
})
|
|
```
|
|
|
|
## Summary
|
|
|
|
| Method | Returns | Contains |
|
|
|--------|---------|----------|
|
|
| `brain.add()` | `string` | The ID of the created entity |
|
|
| `brain.get()` | `Entity \| null` | Full entity object with all fields |
|
|
| `brain.find()` | `Entity[]` | Array of full entity objects |
|
|
| `brain.relate()` | `string` | The ID of the created relationship |
|
|
| `brain.getRelations()` | `Relation[]` | Array of relationship objects |
|