spiral-sdk 0.1.10

Rust SDK for Spiral resource and table APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! Vector Indexes resolved on a branch, and the Tasks that refresh them.

use uuid::Uuid;

use crate::api::tasks::{
    TaskDefinition, TaskReadTarget, TaskReadTargetLatestOnBranch, VectorIndexBuildMode,
    VectorIndexRefreshDefinition,
};
use crate::catalog_types::ProjectBranchId;
use crate::{Error, Project, ResourceAddress, Run, Snapshot, TaskHandle};

const VECTOR_INDEX_KIND: &str = "vector-index";

/// One Vector Index at the commit a [`Snapshot`] selects.
#[derive(Clone)]
pub struct VectorIndex {
    project: Project,
    branch_id: Option<ProjectBranchId>,
    resource_id: Uuid,
    version_id: Uuid,
}

impl Project {
    /// Pin the head of `branch` and resolve the Vector Index at `path`.
    pub async fn vector_index(&self, branch: &str, path: &str) -> Result<VectorIndex, Error> {
        self.branch(branch)
            .await?
            .snapshot()
            .vector_index(path)
            .await
    }
}

impl Snapshot {
    /// Resolve the Vector Index at `path` in this snapshot.
    pub async fn vector_index(&self, path: &str) -> Result<VectorIndex, Error> {
        let address = path.parse::<ResourceAddress>()?;
        if address.reference().is_some() {
            return Err(Error::invalid(
                "select the Vector Index's branch with the snapshot, not an `@` reference",
            ));
        }
        let resource = self.resource_at_path(address.path()).await?;
        if resource.descriptor.kind.0 != VECTOR_INDEX_KIND {
            return Err(Error::invalid(format!("`{path}` is not a Vector Index")));
        }
        Ok(VectorIndex {
            project: self.project.clone(),
            branch_id: self.branch_id,
            resource_id: resource.descriptor.resource_id.as_uuid(),
            version_id: resource.version_id.as_uuid(),
        })
    }
}

impl VectorIndex {
    /// The Vector Index's stable resource identifier.
    pub fn resource_id(&self) -> Uuid {
        self.resource_id
    }

    /// The exact version this snapshot binds.
    pub fn version_id(&self) -> Uuid {
        self.version_id
    }

    /// Submit a build of the index's successor from the latest source Table on this
    /// snapshot's branch.
    ///
    /// Its result lists the new Vector Index version. Returns `None` when a refresh of this
    /// index and branch is already waiting to run.
    pub async fn refresh(
        &self,
        mode: VectorIndexBuildMode,
        run: Run,
    ) -> Result<Option<TaskHandle>, Error> {
        let branch_id = self.branch_id.ok_or_else(|| {
            Error::invalid("refreshing a Vector Index needs a branch snapshot, not an exact commit")
        })?;
        let read = self
            .project
            .client
            .vector_indexes()
            .read_version(self.resource_id, self.version_id)
            .await?;
        let source_resource_id =
            read.definition
                .source_resource_id
                .parse::<Uuid>()
                .map_err(|_| {
                    Error::Protocol("the Vector Index's source is not a resource ID".into())
                })?;
        let definition = TaskDefinition::VectorIndexRefresh(VectorIndexRefreshDefinition {
            read_target: TaskReadTarget::LatestOnBranch(TaskReadTargetLatestOnBranch {
                branch_id: branch_id.as_uuid(),
            }),
            vector_index_id: self.resource_id,
            vector_index_resource_id: self.resource_id,
            source_resource_id,
            mode,
            latest: None,
        });
        self.project.submit_task(definition, None, run).await
    }
}