Appendix I: Complete API Reference

Overview

This chapter provides comprehensive documentation for all public APIs in Vektagraf. Each API method includes detailed signatures, parameters, return types, error conditions, and practical examples. The APIs are organized by functional area to help you quickly find the methods you need.

Learning Objectives

Understand all public API methods and their signatures
Learn parameter types and validation requirements
Master error handling patterns for each API
Explore practical examples for common use cases
Understand deprecated APIs and migration paths

Prerequisites

Basic understanding of Dart programming
Familiarity with Vektagraf core concepts
Knowledge of async/await patterns in Dart

Core Database APIs

VektagrafDatabase

The main interface for interacting with Vektagraf databases in both embedded and hosted modes.

open()

Opens a database connection with optional configuration.

Future<void> open(String path, {VektagrafConfig? config})

Parameters:

path (String): Database path for embedded mode or connection URL for hosted mode
config (VektagrafConfig?, optional): Database configuration options

Returns: Future<void>

Throws:

DatabaseException: If connection fails or path is invalid
ConfigurationException: If configuration is invalid
SecurityException: If authentication fails (hosted mode)

Examples:

// Embedded mode
final database = VektagrafDatabaseImpl();
await database.open('/path/to/database.vektagraf');

// Hosted mode with configuration
final database = VektagrafDatabaseImpl();
await database.open('https://api.example.com', 
  config: VektagrafConfig.hosted(maxMemoryBytes: 512 * 1024 * 1024));

close()

Closes the database connection and releases all resources.

Future<void> close()

Returns: Future<void>

Throws:

DatabaseException: If close operation fails

Example:

await database.close();
```#
### objects<T>()

Returns a VektagrafList for objects of type T, providing enhanced database operations.

```dart
Future<VektagrafList<T>> objects<T>()

Type Parameters:

T: The object type to retrieve

Returns: Future<VektagrafList<T>> - Enhanced list with database connectivity

Throws:

DatabaseException: If database is not open
SchemaException: If type T is not defined in schema

Example:

// Get all users
final users = await database.objects<User>();

// Use fluent API for queries
final activeUsers = users
  .where((user) => user.isActive)
  .take(10);

transaction<R>()

Executes operations within a transaction with ACID guarantees.

Future<R> transaction<R>(Future<R> Function(VektagrafTransaction) operation)

Type Parameters:

R: Return type of the transaction operation

Parameters:

operation: Function that performs operations within the transaction context

Returns: Future<R> - Result of the transaction operation

Throws:

TransactionException: If transaction fails or is rolled back
DatabaseException: If database is not open
ConcurrencyException: If optimistic locking fails

Example:

// Transfer operation with transaction
final result = await database.transaction((txn) async {
  final user = await txn.getById<User>(userId);
  user.balance -= amount;
  
  final recipient = await txn.getById<User>(recipientId);
  recipient.balance += amount;
  
  await txn.update(userId, user, user.revision);
  await txn.update(recipientId, recipient, recipient.revision);
  
  return TransferResult(success: true, transactionId: generateId());
});

graph

Provides access to graph operations for relationship traversal and analysis.

VektagrafGraph get graph

Returns: VektagrafGraph - Graph operations interface

Example:

// Find shortest path between users
final path = await database.graph.shortestPath(
  from: user1.id,
  to: user2.id,
  relationshipType: 'follows'
);

vectorSpace()

Creates or accesses a vector space for similarity search operations.

VektagrafVectorSpace vectorSpace(String name, int dimensions)

Parameters:

name (String): Name of the vector space
dimensions (int): Vector dimensionality (1-4096)

Returns: VektagrafVectorSpace - Vector space interface

Throws:

ArgumentError: If dimensions are invalid (< 1 or > 4096)
DatabaseException: If database is not open

Example:

// Create vector space for embeddings
final embeddings = database.vectorSpace('document_embeddings', 512);

// Add vectors
await embeddings.addVector([0.1, 0.2, ...], metadata: {'docId': '123'});

// Search similar vectors
final results = await embeddings.similaritySearch(queryVector, 10);

isOpen

Checks if the database connection is currently active.

bool get isOpen

Returns: bool - True if database is open, false otherwise

Example:

if (database.isOpen) {
  // Perform database operations
  final users = await database.objects<User>();
}

config

Gets the current database configuration.

VektagrafConfig? get config

Returns: VektagrafConfig? - Current configuration or null if not set

Example:

final config = database.config;
if (config != null) {
  print('Max memory: ${config.maxMemoryBytes} bytes');
  print('Multi-tenant: ${config.isMultiTenantEnabled}');
}

Configuration APIs

VektagrafConfig

Configuration class for database behavior and performance tuning.

Constructor

Creates a new configuration with specified options.

const VektagrafConfig({
  int maxMemoryBytes = 256 * 1024 * 1024,
  int pageSize = 4096,
  bool autoIndexing = true,
  int cacheSize = 1000,
  bool enableWAL = true,
  SyncMode syncMode = SyncMode.normal,
  int? machineId,
  MultiTenancyConfig? multiTenancy,
})

Parameters:

maxMemoryBytes (int): Maximum memory usage in bytes (default: 256MB)
pageSize (int): Storage page size in bytes (default: 4KB)
autoIndexing (bool): Enable automatic index creation (default: true)
cacheSize (int): Cache size for frequently accessed objects (default: 1000)
enableWAL (bool): Enable write-ahead logging (default: true)
syncMode (SyncMode): Durability vs performance trade-off (default: normal)
machineId (int?): Machine ID for distributed systems (auto-detected if null)
multiTenancy (MultiTenancyConfig?): Multi-tenancy configuration

Example:

final config = VektagrafConfig(
  maxMemoryBytes: 512 * 1024 * 1024, // 512MB
  cacheSize: 5000,
  syncMode: SyncMode.full,
  multiTenancy: MultiTenancyConfig(
    enabled: true,
    strictIsolation: true,
  ),
);

embedded()

Factory constructor for embedded mode optimization.

factory VektagrafConfig.embedded({
  int? maxMemoryBytes,
  bool? autoIndexing,
  MultiTenancyConfig? multiTenancy,
})

Parameters:

maxMemoryBytes (int?): Memory limit (default: 128MB for embedded)
autoIndexing (bool?): Enable auto-indexing (default: true)
multiTenancy (MultiTenancyConfig?): Multi-tenancy settings

Returns: VektagrafConfig - Configuration optimized for embedded deployment

Example:

final embeddedConfig = VektagrafConfig.embedded(
  maxMemoryBytes: 64 * 1024 * 1024, // 64MB for mobile
  autoIndexing: true,
);

hosted()

Factory constructor for hosted mode optimization.

factory VektagrafConfig.hosted({
  int? maxMemoryBytes,
  int? cacheSize,
  MultiTenancyConfig? multiTenancy,
})

Parameters:

maxMemoryBytes (int?): Memory limit (default: 512MB for hosted)
cacheSize (int?): Cache size (default: 5000 for hosted)
multiTenancy (MultiTenancyConfig?): Multi-tenancy settings

Returns: VektagrafConfig - Configuration optimized for hosted deployment

Example:

final hostedConfig = VektagrafConfig.hosted(
  maxMemoryBytes: 1024 * 1024 * 1024, // 1GB
  cacheSize: 10000,
  multiTenancy: MultiTenancyConfig(enabled: true),
);

multiTenant()

Factory constructor for multi-tenant hosted mode.

factory VektagrafConfig.multiTenant({
  int? maxMemoryBytes,
  int? cacheSize,
  Map<String, TenantLimitTierConfig>? limitTiers,
  bool strictIsolation = true,
})

Parameters:

maxMemoryBytes (int?): Memory limit (default: 1GB for multi-tenant)
cacheSize (int?): Cache size (default: 10000 for multi-tenant)
limitTiers (Map<String, TenantLimitTierConfig>?): Custom tenant tiers
strictIsolation (bool): Enforce strict tenant isolation (default: true)

Returns: VektagrafConfig - Configuration optimized for multi-tenant deployment

Example:

final multiTenantConfig = VektagrafConfig.multiTenant(
  maxMemoryBytes: 2048 * 1024 * 1024, // 2GB
  strictIsolation: true,
  limitTiers: {
    'premium': TenantLimitTierConfig(
      name: 'premium',
      rateLimit: RateLimitConfig(maxRequests: 5000),
      storageLimit: StorageLimitConfig(maxStorageBytes: 10 * 1024 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 1000000),
    ),
  },
);

SyncMode

Enumeration for synchronization modes balancing durability and performance.

enum SyncMode {
  off,     // No explicit sync (fastest, least durable)
  normal,  // Normal sync on transaction commit (balanced)
  full,    // Full sync on every write (slowest, most durable)
}

Usage:

final config = VektagrafConfig(
  syncMode: SyncMode.full, // Maximum durability
);

Transaction APIs

VektagrafTransaction

Interface for atomic database operations with ACID guarantees.

objects<T>()

Gets objects of type T within the transaction context.

Future<List<T>> objects<T>()

Type Parameters:

T: Object type to retrieve

Returns: Future<List<T>> - List of objects within transaction scope

Example:

await database.transaction((txn) async {
  final users = await txn.objects<User>();
  // Modify users within transaction
});

save<T>()

Saves an object and returns its generated ID.

Future<VektagrafId> save<T>(T object)

Type Parameters:

T: Object type to save

Parameters:

object (T): Object instance to save

Returns: Future<VektagrafId> - Generated unique identifier

Throws:

ValidationException: If object validation fails
StorageException: If storage limit exceeded
TransactionException: If transaction is not active

Example:

await database.transaction((txn) async {
  final user = User(name: 'John', email: 'john@example.com');
  final userId = await txn.save(user);
  print('Saved user with ID: $userId');
});
```#### update<
T>()

Updates an existing object with optimistic concurrency control.

```dart
Future<VektagrafId> update<T>(VektagrafId id, T object, int expectedRevision)

Type Parameters:

T: Object type to update

Parameters:

id (VektagrafId): Unique identifier of object to update
object (T): Updated object instance
expectedRevision (int): Expected revision number for concurrency control

Returns: Future<VektagrafId> - Updated object identifier

Throws:

ConcurrencyException: If expectedRevision doesn't match current revision
NotFoundException: If object with ID doesn't exist
ValidationException: If updated object validation fails

Example:

await database.transaction((txn) async {
  final user = await txn.getById<User>(userId);
  user.lastLogin = DateTime.now();
  
  await txn.update(userId, user, user.revision);
});

saveAll<T>()

Saves multiple objects and returns their IDs.

Future<List<VektagrafId>> saveAll<T>(Iterable<T> objects)

Type Parameters:

T: Object type to save

Parameters:

objects (Iterable<T>): Collection of objects to save

Returns: Future<List<VektagrafId>> - List of generated identifiers

Example:

await database.transaction((txn) async {
  final users = [
    User(name: 'Alice', email: 'alice@example.com'),
    User(name: 'Bob', email: 'bob@example.com'),
  ];
  
  final userIds = await txn.saveAll(users);
  print('Saved ${userIds.length} users');
});

remove()

Removes an object by its ID.

Future<void> remove(VektagrafId id)

Parameters:

id (VektagrafId): Unique identifier of object to remove

Returns: Future<void>

Throws:

NotFoundException: If object with ID doesn't exist
ReferentialIntegrityException: If object has dependent relationships

Example:

await database.transaction((txn) async {
  await txn.remove(userId);
});

removeAll()

Removes multiple objects by their IDs.

Future<void> removeAll(Iterable<VektagrafId> ids)

Parameters:

ids (Iterable<VektagrafId>): Collection of identifiers to remove

Returns: Future<void>

Example:

await database.transaction((txn) async {
  await txn.removeAll([userId1, userId2, userId3]);
});

getById<T>()

Retrieves an object by its ID and type.

Future<T?> getById<T>(VektagrafId id)

Type Parameters:

T: Expected object type

Parameters:

id (VektagrafId): Unique identifier of object to retrieve

Returns: Future<T?> - Object instance or null if not found

Example:

await database.transaction((txn) async {
  final user = await txn.getById<User>(userId);
  if (user != null) {
    print('Found user: ${user.name}');
  }
});

commit()

Commits the transaction, making all changes permanent.

Future<void> commit()

Returns: Future<void>

Throws:

TransactionException: If commit fails or transaction is not active

Note: Transactions are automatically committed when the transaction function completes successfully.

rollback()

Rolls back the transaction, discarding all changes.

Future<void> rollback()

Returns: Future<void>

Note: Transactions are automatically rolled back when exceptions occur.

Transaction State Properties

bool get isActive      // Whether transaction is still active
bool get isCommitted   // Whether transaction has been committed
bool get isRolledBack  // Whether transaction has been rolled back

VektagrafList APIs

VektagrafList<T>

Enhanced list implementation providing database operations with fluent method chaining.

save()

Saves a single object to the database.

Future<VektagrafId> save(T object)

Parameters:

object (T): Object to save

Returns: Future<VektagrafId> - Generated unique identifier

Example:

final users = await database.objects<User>();
final newUser = User(name: 'Charlie', email: 'charlie@example.com');
final userId = await users.save(newUser);

saveAll()

Saves multiple objects to the database.

Future<void> saveAll(Iterable<T> objects)

Parameters:

objects (Iterable<T>): Objects to save

Returns: Future<void>

Example:

final users = await database.objects<User>();
final newUsers = [
  User(name: 'David', email: 'david@example.com'),
  User(name: 'Eve', email: 'eve@example.com'),
];
await users.saveAll(newUsers);

saveAllInTransaction()

Saves multiple objects within a single transaction.

Future<void> saveAllInTransaction(Iterable<T> objects)

Parameters:

objects (Iterable<T>): Objects to save

Returns: Future<void>

Example:

final users = await database.objects<User>();
await users.saveAllInTransaction(newUsers); // Atomic operation

update()

Updates an object with concurrency control.

Future<VektagrafId> update(T object, int expectedRevision)

Parameters:

object (T): Updated object
expectedRevision (int): Expected revision for concurrency control

Returns: Future<VektagrafId> - Updated object identifier

Example:

final users = await database.objects<User>();
final user = users.first;
user.name = 'Updated Name';
await users.update(user, users.revisionOf(user)!);

removeObject()

Removes an object from both list and database.

Future<void> removeObject(T object)

Parameters:

object (T): Object to remove

Returns: Future<void>

Example:

final users = await database.objects<User>();
final userToRemove = users.where((u) => u.email == 'old@example.com').first;
await users.removeObject(userToRemove);

whereProperty()

Executes optimized query by property value.

Future<VektagrafList<T>> whereProperty(String propertyName, dynamic value)

Parameters:

propertyName (String): Name of property to filter by
value (dynamic): Value to match

Returns: Future<VektagrafList<T>> - Filtered results

Example:

final users = await database.objects<User>();
final activeUsers = await users.whereProperty('isActive', true);

wherePropertyRange<V>()

Executes optimized range query on comparable properties.

Future<VektagrafList<T>> wherePropertyRange<V extends Comparable<V>>(
  String propertyName,
  V? minValue,
  V? maxValue,
)

Type Parameters:

V: Comparable value type

Parameters:

propertyName (String): Property name for range query
minValue (V?): Minimum value (inclusive, null for no minimum)
maxValue (V?): Maximum value (inclusive, null for no maximum)

Returns: Future<VektagrafList<T>> - Objects within range

Example:

final users = await database.objects<User>();
final recentUsers = await users.wherePropertyRange<DateTime>(
  'createdAt',
  DateTime.now().subtract(Duration(days: 30)),
  null, // No maximum
);

orderByProperty<V>()

Executes optimized sorted query.

Future<VektagrafList<T>> orderByProperty<V extends Comparable<V>>(
  String propertyName, {
  bool descending = false,
  int? limit,
})

Type Parameters:

V: Comparable value type

Parameters:

propertyName (String): Property to sort by
descending (bool): Sort in descending order (default: false)
limit (int?): Maximum number of results

Returns: Future<VektagrafList<T>> - Sorted results

Example:

final users = await database.objects<User>();
final topUsers = await users.orderByProperty<DateTime>(
  'lastLogin',
  descending: true,
  limit: 10,
);

Vector Search Methods

whereSimilar()

Performs vector similarity search on objects.

Future<VektagrafList<T>> whereSimilar(
  String vectorField,
  List<double> queryVector, {
  int limit = 10,
  double? threshold,
})

Parameters:

vectorField (String): Name of vector field to search
queryVector (List): Query vector for similarity comparison
limit (int): Maximum results to return (default: 10)
threshold (double?): Minimum similarity threshold

Returns: Future<VektagrafList<T>> - Objects ranked by similarity

Example:

final documents = await database.objects<Document>();
final queryEmbedding = await generateEmbedding('search query');
final similar = await documents.whereSimilar(
  'embedding',
  queryEmbedding,
  limit: 5,
  threshold: 0.7,
);

whereSimilarTo()

Performs similarity search using reference object's vector.

Future<VektagrafList<T>> whereSimilarTo(
  T referenceObject,
  String vectorField, {
  int limit = 10,
})

Parameters:

referenceObject (T): Object whose vector to use as query
vectorField (String): Vector field name
limit (int): Maximum results (default: 10)

Returns: Future<VektagrafList<T>> - Similar objects

Example:

final documents = await database.objects<Document>();
final referenceDoc = documents.first;
final similar = await documents.whereSimilarTo(
  referenceDoc,
  'embedding',
  limit: 5,
);

Relationship Traversal Methods

expandRelation<R>()

Expands objects through named relationships.

Future<VektagrafList<R>> expandRelation<R>(String relationName)

Type Parameters:

Parameters:

relationName (String): Name of relationship to traverse

Returns: Future<VektagrafList<R>> - Related objects

Example:

final users = await database.objects<User>();
final posts = await users.expandRelation<Post>('posts');

whereRelated<R>()

Filters objects based on related object properties.

Future<VektagrafList<T>> whereRelated<R>(
  String relationName,
  bool Function(R) relationTest,
)

Type Parameters:

Parameters:

relationName (String): Relationship name
relationTest (bool Function(R)): Predicate for related objects

Returns: Future<VektagrafList<T>> - Objects with matching related objects

Example:

final users = await database.objects<User>();
final usersWithRecentPosts = await users.whereRelated<Post>(
  'posts',
  (post) => post.createdAt.isAfter(DateTime.now().subtract(Duration(days: 7))),
);

whereHasRelation()

Filters objects that have at least one related object.

Future<VektagrafList<T>> whereHasRelation(String relationName)

Parameters:

relationName (String): Relationship name to check

Returns: Future<VektagrafList<T>> - Objects with the relationship

Example:

final users = await database.objects<User>();
final usersWithPosts = await users.whereHasRelation('posts');

Metadata Access Methods

idOf()

Gets the VektagrafId for an object.

VektagrafId? idOf(T object)

Parameters:

object (T): Object to get ID for

Returns: VektagrafId? - Object ID or null if not saved

Example:

final users = await database.objects<User>();
final user = users.first;
final userId = users.idOf(user);

revisionOf()

Gets the revision number for concurrency control.

int? revisionOf(T object)

Parameters:

object (T): Object to get revision for

Returns: int? - Current revision or null if not saved

Example:

final users = await database.objects<User>();
final user = users.first;
final revision = users.revisionOf(user);

createdAt() / updatedAt()

Gets creation and update timestamps.

DateTime? createdAt(T object)
DateTime? updatedAt(T object)

Parameters:

object (T): Object to get timestamp for

Returns: DateTime? - Timestamp or null if not available

Example:

final users = await database.objects<User>();
final user = users.first;
print('Created: ${users.createdAt(user)}');
print('Updated: ${users.updatedAt(user)}');

Transaction Support

withTransaction<R>()

Executes operations within a transaction scope.

Future<R> withTransaction<R>(Future<R> Function(VektagrafList<T>) operation)

Type Parameters:

R: Return type of operation

Parameters:

operation: Function to execute within transaction

Returns: Future<R> - Result of operation

Example:

final users = await database.objects<User>();
final result = await users.withTransaction((txnUsers) async {
  // All operations on txnUsers are within transaction
  await txnUsers.saveAll(newUsers);
  return newUsers.length;
});

VektagrafId APIs

VektagrafId

Snowflake-like identifier system providing time-ordered unique IDs.

Constructor

Creates a VektagrafId with specified components.

const VektagrafId({
  required int timestamp,
  required int machineId,
  required int sequence,
})

Parameters:

timestamp (int): 42-bit timestamp (milliseconds since epoch)
machineId (int): 10-bit machine identifier
sequence (int): 12-bit sequence number

fromInt()

Creates a VektagrafId from a 64-bit integer.

factory VektagrafId.fromInt(int value)

Parameters:

value (int): 64-bit integer representation

Returns: VektagrafId - Decoded identifier

Example:

final id = VektagrafId.fromInt(1234567890123456);
print('Timestamp: ${id.timestamp}');
print('Machine: ${id.machineId}');
print('Sequence: ${id.sequence}');

generate()

Generates a new VektagrafId with current timestamp.

static VektagrafId generate()

Returns: VektagrafId - New unique identifier

Example:

final newId = VektagrafId.generate();
print('Generated ID: $newId');

toInt()

Converts the ID to a 64-bit integer.

int toInt()

Returns: int - 64-bit integer representation

Example:

final id = VektagrafId.generate();
final intValue = id.toInt();
print('Integer value: $intValue');

toBinary() / fromBinary()

Binary serialization for efficient storage.

Uint8List toBinary()
static VektagrafId fromBinary(Uint8List bytes)

Example:

final id = VektagrafId.generate();
final bytes = id.toBinary();
final restored = VektagrafId.fromBinary(bytes);
assert(id == restored);

Comparison

VektagrafId implements natural time-ordering comparison.

int compareTo(VektagrafId other)

Example:

final id1 = VektagrafId.generate();
await Future.delayed(Duration(milliseconds: 1));
final id2 = VektagrafId.generate();

assert(id1.compareTo(id2) < 0); // id1 is earlier than id2

Vector Space APIs

VektagrafVectorSpace

Interface for vector storage and similarity search operations.

addVector()

Adds a vector to the space with optional metadata.

Future<VektagrafId> addVector(List<double> vector, {Map<String, dynamic>? metadata})

Parameters:

vector (List): Vector data (must match space dimensions)
metadata (Map<String, dynamic>?): Optional metadata

Returns: Future<VektagrafId> - Unique identifier for stored vector

Throws:

ArgumentError: If vector dimensions don't match space
ValidationError: If vector contains invalid values (NaN, infinity)

Example:

final embeddings = database.vectorSpace('document_embeddings', 512);
final vectorId = await embeddings.addVector(
  documentEmbedding,
  metadata: {
    'documentId': 'doc123',
    'title': 'Important Document',
    'category': 'research',
  },
);

similaritySearch()

Performs similarity search for query vector.

Future<List<VectorSearchResult>> similaritySearch(
  List<double> queryVector,
  int limit, {
  DistanceMetric metric = DistanceMetric.cosine,
})

Parameters:

queryVector (List): Query vector for similarity comparison
limit (int): Maximum number of results to return
metric (DistanceMetric): Distance metric to use (default: cosine)

Returns: Future<List<VectorSearchResult>> - Results ranked by similarity

Example:

final embeddings = database.vectorSpace('document_embeddings', 512);
final results = await embeddings.similaritySearch(
  queryEmbedding,
  10,
  metric: DistanceMetric.cosine,
);

for (final result in results) {
  print('Document: ${result.metadata['title']}');
  print('Similarity: ${result.score}');
}

hybridSearch()

Combines vector similarity with metadata filtering.

Future<List<VectorSearchResult>> hybridSearch(
  List<double> queryVector,
  bool Function(Map<String, dynamic>) metadataFilter,
  int limit, {
  DistanceMetric metric = DistanceMetric.cosine,
})

Parameters:

queryVector (List): Query vector
metadataFilter (bool Function(Map<String, dynamic>)): Metadata filter predicate
limit (int): Maximum results
metric (DistanceMetric): Distance metric

Returns: Future<List<VectorSearchResult>> - Filtered and ranked results

Example:

final embeddings = database.vectorSpace('document_embeddings', 512);
final results = await embeddings.hybridSearch(
  queryEmbedding,
  (metadata) => metadata['category'] == 'research' && 
                 metadata['published'] == true,
  5,
);

removeVector()

Removes a vector by its ID.

Future<void> removeVector(VektagrafId id)

Parameters:

id (VektagrafId): Vector identifier to remove

Returns: Future<void>

Example:

await embeddings.removeVector(vectorId);

updateMetadata()

Updates metadata for an existing vector.

Future<void> updateMetadata(VektagrafId id, Map<String, dynamic> metadata)

Parameters:

id (VektagrafId): Vector identifier
metadata (Map<String, dynamic>): New metadata

Returns: Future<void>

Example:

await embeddings.updateMetadata(vectorId, {
  'title': 'Updated Document Title',
  'lastModified': DateTime.now().toIso8601String(),
});

vectorCount

Gets the total number of vectors in the space.

Future<int> get vectorCount

Returns: Future<int> - Number of vectors stored

Example:

final count = await embeddings.vectorCount;
print('Total vectors: $count');

VectorSearchResult

Result from vector similarity search operations.

class VectorSearchResult {
  final VektagrafId id;           // Vector identifier
  final double score;             // Similarity score (higher = more similar)
  final double distance;          // Distance value (lower = more similar)
  final List<double> vector;      // Vector data
  final Map<String, dynamic> metadata; // Associated metadata
}

DistanceMetric

Supported distance metrics for vector similarity.

enum DistanceMetric {
  cosine,        // Cosine distance (1 - cosine similarity)
  euclidean,     // Euclidean (L2) distance
  innerProduct,  // Inner product distance
}

Usage:

// Different metrics for different use cases
final results1 = await embeddings.similaritySearch(query, 10, 
  metric: DistanceMetric.cosine);      // Good for normalized vectors

final results2 = await embeddings.similaritySearch(query, 10,
  metric: DistanceMetric.euclidean);   // Good for spatial data

final results3 = await embeddings.similaritySearch(query, 10,
  metric: DistanceMetric.innerProduct); // Good for recommendation systems
```## Schema
 APIs

### VektagrafSchemaParser

Parser for Vektagraf JSON schemas with validation and error handling.

#### parseFromString()

Parses a schema from JSON string.

```dart
VektagrafSchema parseFromString(String jsonString)

Parameters:

jsonString (String): JSON schema definition

Returns: VektagrafSchema - Parsed schema object

Throws:

SchemaParseException: If JSON is invalid or schema format is incorrect
SystemSchemaException: If system schema validation fails

Example:

final parser = VektagrafSchemaParser();
final schemaJson = '''
{
  "models": {
    "User": {
      "name": "string",
      "email": "string",
      "age": "int32?",
      "embedding": {
        "type": "vector",
        "dimensions": 512,
        "distance_function": "cosine"
      }
    }
  }
}
''';

final schema = parser.parseFromString(schemaJson);

parseFromFile()

Parses a schema from a file.

Future<VektagrafSchema> parseFromFile(String filePath)

Parameters:

filePath (String): Path to schema file

Returns: Future<VektagrafSchema> - Parsed schema

Throws:

SchemaParseException: If file not found or parsing fails

Example:

final parser = VektagrafSchemaParser();
final schema = await parser.parseFromFile('schema.json');

parseFromJson()

Parses a schema from JSON map.

VektagrafSchema parseFromJson(Map<String, dynamic> json)

Parameters:

json (Map<String, dynamic>): JSON schema data

Returns: VektagrafSchema - Parsed schema

Example:

final parser = VektagrafSchemaParser();
final jsonData = jsonDecode(schemaString);
final schema = parser.parseFromJson(jsonData);

VektagrafSchema

Represents a complete Vektagraf schema with models and metadata.

class VektagrafSchema {
  final Map<String, ModelDefinition> models;    // Model definitions
  final Map<String, dynamic> metadata;          // Schema metadata
  final Map<String, dynamic> security;          // Security configuration
  final bool isSystemSchema;                     // System schema flag
  final String? schemaVersion;                   // Schema version
}

Example:

final schema = parser.parseFromString(schemaJson);

// Access models
for (final model in schema.models.values) {
  print('Model: ${model.name}');
  
  // Check for vector fields
  if (model.hasVectorFields) {
    print('  Has vector fields: ${model.vectorFields.length}');
  }
  
  // Check for relationships
  if (model.hasRelationshipFields) {
    print('  Has relationships: ${model.relationshipFields.length}');
  }
}

ModelDefinition

Represents a model definition with fields and metadata.

class ModelDefinition {
  final String name;                                    // Model name
  final Map<String, FieldDefinition> fields;          // Field definitions
  final Map<String, dynamic> metadata;                // Model metadata
  final List<String> inheritsFrom;                    // Inheritance chain
  
  // Convenience getters
  List<FieldDefinition> get vectorFields;             // Vector fields only
  List<FieldDefinition> get relationshipFields;      // Relationship fields only
  bool get hasVectorFields;                           // Has any vector fields
  bool get hasRelationshipFields;                     // Has any relationships
}

FieldDefinition

Represents a field definition with type and configuration.

class FieldDefinition {
  final String name;                              // Field name
  final String type;                              // Field type
  final bool isOptional;                          // Optional field flag
  final Map<String, dynamic> metadata;           // Field metadata
  final VectorConfig? vectorConfig;               // Vector configuration
  final RelationshipConfig? relationshipConfig;  // Relationship configuration
  
  // Convenience getters
  bool get isVector;                              // Is vector field
  bool get isRelationship;                        // Is relationship field
  bool get isList;                                // Is list type
  bool get isSet;                                 // Is set type
  bool get isMap;                                 // Is map type
  String get baseType;                            // Base type without collection wrappers
}

VectorConfig

Configuration for vector fields.

class VectorConfig {
  final int dimensions;                    // Vector dimensions (1-4096)
  final String distanceFunction;          // Distance function ('cosine', 'euclidean', 'inner_product')
  final Map<String, dynamic> metadata;    // Additional metadata
}

RelationshipConfig

Configuration for relationship fields.

class RelationshipConfig {
  final String targetModel;        // Target model name
  final RelationType type;         // Relationship type
  final bool isBidirectional;      // Bidirectional relationship flag
  final String? inverseField;      // Inverse field name
}

enum RelationType {
  oneToOne,    // @Model
  oneToMany,   // [@Model]
  manyToMany,  // {@Model} or <key, @Model>
}

Schema Exceptions

SchemaParseException

Thrown when schema parsing fails.

class SchemaParseException implements Exception {
  final String message;    // Error message
  final String? field;     // Field name (if field-specific error)
  final String? model;     // Model name (if model-specific error)
}

SystemSchemaException

Thrown when system schema validation fails.

class SystemSchemaException implements Exception {
  final String message;                    // Error message
  final String? schemaVersion;             // Schema version
  final List<String> validationErrors;    // Detailed validation errors
}

Example Error Handling:

try {
  final schema = parser.parseFromString(schemaJson);
} on SchemaParseException catch (e) {
  print('Schema parsing failed: ${e.message}');
  if (e.model != null) print('Model: ${e.model}');
  if (e.field != null) print('Field: ${e.field}');
} on SystemSchemaException catch (e) {
  print('System schema validation failed: ${e.message}');
  for (final error in e.validationErrors) {
    print('  - $error');
  }
}

Factory APIs

VektagrafFactory

Factory for creating database instances in different deployment modes.

create()

Creates a database instance based on connection string.

static Future<VektagrafDatabase> create(
  String connectionString, {
  VektagrafConfig? config,
  VektagrafClientConfig? clientConfig,
})

Parameters:

connectionString (String): File path (embedded) or URL (hosted)
config (VektagrafConfig?): Database configuration
clientConfig (VektagrafClientConfig?): Client configuration (required for hosted)

Returns: Future<VektagrafDatabase> - Database instance

Example:

// Embedded mode
final embeddedDb = await VektagrafFactory.create(
  '/path/to/database.vektagraf',
  config: VektagrafConfig.embedded(),
);

// Hosted mode
final hostedDb = await VektagrafFactory.create(
  'https://api.example.com',
  config: VektagrafConfig.hosted(),
  clientConfig: VektagrafClientConfig(
    username: 'user',
    password: 'pass',
  ),
);

createEmbedded()

Creates an embedded database instance.

static Future<VektagrafDatabase> createEmbedded(
  String databasePath, {
  VektagrafConfig? config,
})

Parameters:

databasePath (String): Path to database file
config (VektagrafConfig?): Database configuration

Returns: Future<VektagrafDatabase> - Embedded database instance

Example:

final database = await VektagrafFactory.createEmbedded(
  'app_data.vektagraf',
  config: VektagrafConfig.embedded(maxMemoryBytes: 128 * 1024 * 1024),
);

createClient()

Creates a hosted database client.

static Future<VektagrafDatabase> createClient(
  String serverUrl,
  VektagrafClientConfig clientConfig, {
  VektagrafConfig? config,
})

Parameters:

serverUrl (String): Server URL
clientConfig (VektagrafClientConfig): Client authentication and settings
config (VektagrafConfig?): Database configuration

Returns: Future<VektagrafDatabase> - Client database instance

Example:

final client = await VektagrafFactory.createClient(
  'https://vektagraf.example.com',
  VektagrafClientConfig(
    username: 'api_user',
    password: 'secure_password',
    timeout: Duration(seconds: 30),
  ),
);

isHostedMode()

Checks if connection string indicates hosted mode.

static bool isHostedMode(String connectionString)

Parameters:

connectionString (String): Connection string to check

Returns: bool - True if hosted mode, false if embedded

Example:

final isHosted = VektagrafFactory.isHostedMode('https://api.example.com');
// Returns: true

final isEmbedded = VektagrafFactory.isHostedMode('/path/to/db.vektagraf');
// Returns: false

Multi-Tenancy APIs

TenantConfig

Complete tenant configuration with limits and settings.

Constructor

Creates a tenant configuration.

const TenantConfig({
  required String tenantId,
  required String name,
  required TenantLimitTier tier,
  required RateLimitConfig rateLimit,
  required StorageLimitConfig storageLimit,
  required RequestLimitConfig requestLimit,
  bool enabled = true,
  required DateTime createdAt,
  DateTime? updatedAt,
  Map<String, dynamic> customSettings = const {},
})

forTier()

Factory constructor for predefined tier configurations.

factory TenantConfig.forTier({
  required String tenantId,
  required String name,
  required TenantLimitTier tier,
  Map<String, dynamic> customSettings = const {},
  required VektagrafConfig dbConfig,
})

Parameters:

tenantId (String): Unique tenant identifier
name (String): Human-readable tenant name
tier (TenantLimitTier): Predefined tier (tier1, tier2, tier3, tier4, custom)
customSettings (Map<String, dynamic>): Additional settings
dbConfig (VektagrafConfig): Database configuration for tier defaults

Returns: TenantConfig - Configured tenant

Example:

final tenantConfig = TenantConfig.forTier(
  tenantId: 'tenant_123',
  name: 'Acme Corporation',
  tier: TenantLimitTier.tier2,
  dbConfig: databaseConfig,
  customSettings: {
    'industry': 'technology',
    'region': 'us-west',
  },
);

copyWith()

Creates updated tenant configuration.

TenantConfig copyWith({
  String? name,
  TenantLimitTier? tier,
  RateLimitConfig? rateLimit,
  StorageLimitConfig? storageLimit,
  RequestLimitConfig? requestLimit,
  bool? enabled,
  Map<String, dynamic>? customSettings,
})

Example:

final updatedConfig = tenantConfig.copyWith(
  tier: TenantLimitTier.tier3,
  enabled: true,
);

RateLimitConfig

Rate limiting configuration for tenant requests.

class RateLimitConfig {
  final int maxRequests;              // Max requests per time window
  final Duration timeWindow;          // Time window duration
  final bool slidingWindow;           // Sliding vs fixed window
  final int burstAllowance;          // Additional burst requests
  final Set<String> operationTypes;  // Operations to rate limit
}

Example:

final rateLimit = RateLimitConfig(
  maxRequests: 1000,
  timeWindow: Duration(minutes: 1),
  slidingWindow: true,
  burstAllowance: 100,
  operationTypes: {'read', 'write', 'query', 'vector_search'},
);

StorageLimitConfig

Storage limits configuration for tenant data.

class StorageLimitConfig {
  final int maxStorageBytes;          // Maximum storage in bytes
  final int? maxObjects;              // Maximum number of objects
  final int? maxObjectSize;           // Maximum size per object
  final int? maxVectors;              // Maximum number of vectors
  final int? maxVectorDimensions;     // Maximum vector dimensions
  final double warningThreshold;      // Warning threshold (0.0-1.0)
  final bool hardLimits;              // Enforce hard limits
}

Example:

final storageLimit = StorageLimitConfig(
  maxStorageBytes: 10 * 1024 * 1024 * 1024, // 10GB
  maxObjects: 100000,
  maxObjectSize: 100 * 1024 * 1024, // 100MB
  maxVectors: 50000,
  maxVectorDimensions: 1024,
  warningThreshold: 0.8,
  hardLimits: true,
);

RequestLimitConfig

Request limits and priority configuration.

class RequestLimitConfig {
  final int? dailyLimit;                    // Daily request limit
  final int? monthlyLimit;                  // Monthly request limit
  final int? concurrentLimit;               // Concurrent request limit
  final int? complexityLimit;               // Query complexity limit
  final int? maxResultSize;                 // Maximum result size
  final Set<String> allowedOperations;      // Allowed operation types
  final RequestPriority priority;           // Request priority level
}

enum RequestPriority {
  low,
  normal,
  high,
  critical,
}

Example:

final requestLimit = RequestLimitConfig(
  dailyLimit: 100000,
  monthlyLimit: 2000000,
  concurrentLimit: 50,
  complexityLimit: 1000,
  maxResultSize: 10000,
  allowedOperations: {
    'read', 'write', 'delete', 'query', 'vector_search', 'graph_traverse'
  },
  priority: RequestPriority.high,
);

TenantLimitTier

Predefined tenant limit tiers.

enum TenantLimitTier {
  tier1,    // Basic tier
  tier2,    // Standard tier
  tier3,    // Professional tier
  tier4,    // Enterprise tier
  custom,   // Custom configuration
}

Error Handling

Common Exception Types

DatabaseException

Base exception for database operations.

class DatabaseException implements Exception {
  final String message;
  final String? operation;
  final dynamic cause;
}

TransactionException

Exception for transaction-related errors.

class TransactionException extends DatabaseException {
  final String transactionId;
  final TransactionState state;
}

ConcurrencyException

Exception for optimistic locking failures.

class ConcurrencyException extends DatabaseException {
  final VektagrafId objectId;
  final int expectedRevision;
  final int actualRevision;
}

ValidationException

Exception for object validation failures.

class ValidationException extends DatabaseException {
  final String objectType;
  final Map<String, List<String>> fieldErrors;
}

SecurityException

Exception for security and authentication failures.

class SecurityException extends DatabaseException {
  final String? tenantId;
  final String? operation;
  final SecurityErrorType errorType;
}

enum SecurityErrorType {
  authentication,
  authorization,
  rateLimitExceeded,
  quotaExceeded,
}

Error Handling Patterns

Basic Error Handling

try {
  final users = await database.objects<User>();
  await users.save(newUser);
} on ValidationException catch (e) {
  print('Validation failed: ${e.message}');
  for (final entry in e.fieldErrors.entries) {
    print('${entry.key}: ${entry.value.join(', ')}');
  }
} on DatabaseException catch (e) {
  print('Database error: ${e.message}');
  if (e.cause != null) {
    print('Caused by: ${e.cause}');
  }
}

Transaction Error Handling

try {
  await database.transaction((txn) async {
    // Transaction operations
  });
} on ConcurrencyException catch (e) {
  print('Concurrency conflict for object ${e.objectId}');
  print('Expected revision: ${e.expectedRevision}');
  print('Actual revision: ${e.actualRevision}');
  // Retry with updated revision
} on TransactionException catch (e) {
  print('Transaction failed: ${e.message}');
  print('Transaction ID: ${e.transactionId}');
  print('State: ${e.state}');
}

Multi-Tenant Error Handling

try {
  await database.objects<Document>().save(document);
} on SecurityException catch (e) {
  switch (e.errorType) {
    case SecurityErrorType.rateLimitExceeded:
      print('Rate limit exceeded for tenant ${e.tenantId}');
      // Implement backoff strategy
      break;
    case SecurityErrorType.quotaExceeded:
      print('Storage quota exceeded for tenant ${e.tenantId}');
      // Notify tenant to upgrade
      break;
    case SecurityErrorType.authorization:
      print('Insufficient permissions for operation ${e.operation}');
      break;
  }
}

Deprecated APIs and Migration

Deprecated Methods

VektagrafList.whereSimilarLegacy()

Status: Deprecated in v1.2.0, will be removed in v2.0.0

Replacement: Use whereSimilar() with named parameters

// Deprecated
final results = await list.whereSimilarLegacy(
  queryVector,
  limit: 10,
  vectorField: 'embedding',
);

// New approach
final results = await list.whereSimilar(
  'embedding',
  queryVector,
  limit: 10,
);

VektagrafConfig.machineId

Status: Deprecated in v1.3.0, auto-detection preferred

Migration: Remove explicit machineId setting, use auto-detection

// Deprecated
final config = VektagrafConfig(
  machineId: 123,
  // other settings
);

// New approach - auto-detection
final config = VektagrafConfig(
  // machineId will be auto-detected
);

Breaking Changes

v1.0.0 to v1.1.0

VektagrafList.expand() now requires type parameter
Vector search methods moved from database to VektagrafList
Schema parser validates system schemas more strictly

v1.1.0 to v1.2.0

Multi-tenancy configuration structure changed
Rate limiting configuration expanded
New security exception types introduced

Migration Utilities

Schema Migration

// Utility to migrate schemas between versions
class SchemaMigrator {
  static Future<VektagrafSchema> migrateToLatest(
    VektagrafSchema oldSchema,
    String targetVersion,
  ) async {
    // Migration logic
  }
}

Configuration Migration

// Utility to migrate configurations
class ConfigMigrator {
  static VektagrafConfig migrateConfig(
    Map<String, dynamic> oldConfig,
    String fromVersion,
    String toVersion,
  ) {
    // Migration logic
  }
}

Summary

This chapter provided comprehensive documentation for all public APIs in Vektagraf, including:

Core Database APIs: Main database interface with connection management
Configuration APIs: Database and multi-tenant configuration options
Transaction APIs: ACID transaction support with concurrency control
VektagrafList APIs: Enhanced list operations with database connectivity
VektagrafId APIs: Unique identifier system with time ordering
Vector Space APIs: Vector storage and similarity search operations
Schema APIs: JSON schema parsing and validation
Factory APIs: Database instance creation for different deployment modes
Multi-Tenancy APIs: Tenant configuration and limit management
Error Handling: Exception types and handling patterns
Migration Guide: Deprecated APIs and upgrade procedures

Each API includes detailed method signatures, parameters, return types, error conditions, and practical examples. Use this reference to implement robust Vektagraf applications with proper error handling and best practices.

Next Steps

Chapter 24: Configuration Reference - Detailed configuration options
Chapter 25: Error Codes and Troubleshooting - Comprehensive error handling
Chapter 26: Migration and Upgrade Guides - Version compatibility and upgrades
Part I: Foundations - Core concepts and getting started
Part II: Core Features - Database operations and advanced features