Development build. This page describes main, not a released package. The latest published Lodestar.Embeddings is 0.8.0 — read its documentation.

Home › Embeddings › Vector search

Writes the index out, asynchronously.

public Task SaveAsync(Stream destination, CancellationToken cancellationToken = default)

Parameters — destination is a writable stream, never disposed by this method. cancellationToken cancels the write.

Returns — Task, completing when the index has been written and flushed.

Exceptions — ArgumentException when the stream cannot be written to, refused before the vectors and ids are checked (#1641), and when an id is beyond what the JSON writer can write — the writer's own, as 0.8.0 raised it (#1618, #1646). IndexOutOfRangeException, the writer's own as well, for a string whose escaped form passes its buffer, as 0.8.0 raised it. ArgumentNullException when destination is null. InvalidDataException when any stored vector holds a non-finite component. InvalidOperationException when the vector block, base64-encoded, is longer than the one array a load decodes it into (#1322). OperationCanceledException when cancellationToken is signalled.

Example — the asynchronous half of a round trip.

using Lodestar.Embeddings.Search;

static async Task<string> RoundTripAsync()
{
    var index = new EmbeddingIndex(dimension: 2);
    index.Add(new float[] { 1f, 0f }, "east");

    using var buffer = new MemoryStream();
    await index.SaveAsync(buffer);
    buffer.Position = 0;

    EmbeddingIndex restored = await EmbeddingIndex.LoadAsync(buffer);
    return restored.GetId(0)!;
}

string label = RoundTripAsync().GetAwaiter().GetResult();  // => east

The GetAwaiter().GetResult() is only what lets a synchronous example drive an async one; in async code the call is simply await.

Remarks — the same format and the same refusals as Save; only the I/O is asynchronous. There is no string overload, because opening the file is the synchronous part and a caller who wants one can open it and hand over the stream.

Cancellation stops the write; it does not undo it. The stream belongs to the caller and is never disposed here, so whatever had already been written stays written. Save to a temporary file and move it into place if a half-written artifact could be mistaken for a good one.

Applies to — net10.0, netstandard2.0.

See also — EmbeddingIndex.Save, EmbeddingIndex.LoadAsync, EmbeddingIndex.