diff --git a/connectors/clients/elixir/lib/verisim_client.ex b/connectors/clients/elixir/lib/verisim_client.ex index 660abb4..237fdbf 100644 --- a/connectors/clients/elixir/lib/verisim_client.ex +++ b/connectors/clients/elixir/lib/verisim_client.ex @@ -7,7 +7,7 @@ defmodule VeriSimClient do Holds connection configuration (base URL, authentication, timeout) and provides low-level HTTP helpers that the domain modules (`Octad`, `Search`, - `Drift`, `Provenance`, `Vql`, `Federation`) delegate to. + `Drift`, `Provenance`, `Vcl`, `Federation`) delegate to. ## Quick Start diff --git a/connectors/clients/elixir/lib/verisim_client/types.ex b/connectors/clients/elixir/lib/verisim_client/types.ex index b607da2..d5b5634 100644 --- a/connectors/clients/elixir/lib/verisim_client/types.ex +++ b/connectors/clients/elixir/lib/verisim_client/types.ex @@ -247,13 +247,13 @@ defmodule VeriSimClient.Types do } # --------------------------------------------------------------------------- - # VqlResponse + # VclResponse # --------------------------------------------------------------------------- @typedoc """ - Response from a VQL query execution or explain request. + Response from a VCL query execution or explain request. """ - @type vql_response :: %{ + @type vcl_response :: %{ required(:success) => boolean(), required(:statement_type) => String.t(), required(:row_count) => non_neg_integer(), diff --git a/connectors/clients/elixir/lib/verisim_client/vcl.ex b/connectors/clients/elixir/lib/verisim_client/vcl.ex index 3c7f26a..c35c849 100644 --- a/connectors/clients/elixir/lib/verisim_client/vcl.ex +++ b/connectors/clients/elixir/lib/verisim_client/vcl.ex @@ -1,29 +1,29 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -defmodule VeriSimClient.Vql do +defmodule VeriSimClient.Vcl do @moduledoc """ - VeriSim Query Language (VQL) execution for VeriSimDB. + VeriSim Query Language (VCL) execution for VeriSimDB. - VQL is VeriSimDB's native query language, supporting SQL-like syntax extended + VCL is VeriSimDB's native query language, supporting SQL-like syntax extended with multi-modal operations (vector similarity, graph traversal, spatial predicates, drift thresholds, etc.). This module provides methods to execute - VQL statements and retrieve explain / query plans. + VCL statements and retrieve explain / query plans. ## Examples {:ok, client} = VeriSimClient.new("http://localhost:8080") - {:ok, result} = VeriSimClient.Vql.execute(client, "SELECT * FROM octads WHERE drift > 0.5") + {:ok, result} = VeriSimClient.Vcl.execute(client, "SELECT * FROM octads WHERE drift > 0.5") IO.puts("Rows returned: \#{result["row_count"]}") - {:ok, plan} = VeriSimClient.Vql.explain(client, "SELECT * FROM octads WHERE drift > 0.5") + {:ok, plan} = VeriSimClient.Vcl.explain(client, "SELECT * FROM octads WHERE drift > 0.5") """ alias VeriSimClient.Types @doc """ - Execute a VQL statement against the VeriSimDB instance. + Execute a VCL statement against the VeriSimDB instance. Supports SELECT, INSERT, UPDATE, DELETE, and VeriSimDB-specific statements like `DRIFT CHECK`, `NORMALIZE`, and `FEDERATE`. @@ -31,17 +31,17 @@ defmodule VeriSimClient.Vql do ## Parameters * `client` — A `VeriSimClient.t()` connection. - * `query` — The VQL statement string. + * `query` — The VCL statement string. """ @spec execute(VeriSimClient.t(), String.t()) :: - {:ok, Types.vql_response()} | {:error, term()} + {:ok, Types.vcl_response()} | {:error, term()} def execute(%VeriSimClient{} = client, query) when is_binary(query) do body = %{query: query} - VeriSimClient.do_post(client, "/api/v1/vql/execute", body) + VeriSimClient.do_post(client, "/api/v1/vcl/execute", body) end @doc """ - Request an explain / query plan for a VQL statement without executing it. + Request an explain / query plan for a VCL statement without executing it. Useful for understanding which modalities, indices, and federation peers would be involved in a query. @@ -49,12 +49,12 @@ defmodule VeriSimClient.Vql do ## Parameters * `client` — A `VeriSimClient.t()` connection. - * `query` — The VQL statement string to explain. + * `query` — The VCL statement string to explain. """ @spec explain(VeriSimClient.t(), String.t()) :: - {:ok, Types.vql_response()} | {:error, term()} + {:ok, Types.vcl_response()} | {:error, term()} def explain(%VeriSimClient{} = client, query) when is_binary(query) do body = %{query: query} - VeriSimClient.do_post(client, "/api/v1/vql/explain", body) + VeriSimClient.do_post(client, "/api/v1/vcl/explain", body) end end diff --git a/connectors/clients/elixir/mix.exs b/connectors/clients/elixir/mix.exs index ae81769..0b9807d 100644 --- a/connectors/clients/elixir/mix.exs +++ b/connectors/clients/elixir/mix.exs @@ -6,7 +6,7 @@ defmodule VeriSimClient.MixProject do Mix project configuration for the VeriSimDB Elixir client SDK. Provides octad entity management, multi-modal search (text, vector, spatial), - drift detection, provenance chain operations, VQL query execution, and + drift detection, provenance chain operations, VCL query execution, and federation across distributed VeriSimDB instances. """ diff --git a/connectors/clients/julia/src/VeriSimDBClient.jl b/connectors/clients/julia/src/VeriSimDBClient.jl index 2dbf9a5..46b9e75 100644 --- a/connectors/clients/julia/src/VeriSimDBClient.jl +++ b/connectors/clients/julia/src/VeriSimDBClient.jl @@ -4,7 +4,7 @@ # VeriSimDB Julia Client — Main module. # # This is the top-level module for the VeriSimDB Julia client SDK. It aggregates -# all submodules (types, error, client, octad, search, drift, provenance, vql, +# all submodules (types, error, client, octad, search, drift, provenance, vcl, # federation) and re-exports the public API. # # Usage: @@ -30,7 +30,7 @@ include("octad.jl") include("search.jl") include("drift.jl") include("provenance.jl") -include("vql.jl") +include("vcl.jl") include("federation.jl") # --- Public exports --- @@ -44,7 +44,7 @@ export GraphData, GraphEdge, VectorData, TensorData, DocumentContent, SpatialDat export DriftScore, DriftLevel, DriftStatusReport export ProvenanceEvent, ProvenanceChain, ProvenanceEventInput export PaginatedResponse, SearchResult -export VqlResult, VqlExplanation +export VclResult, VclExplanation export FederationPeer # Octad CRUD @@ -60,8 +60,8 @@ export get_drift_score, drift_status, normalize_drift # Provenance export get_provenance_chain, record_provenance, verify_provenance -# VQL -export execute_vql, explain_vql +# VCL +export execute_vcl, explain_vcl # Federation export register_peer, list_peers, federated_query diff --git a/connectors/clients/julia/src/error.jl b/connectors/clients/julia/src/error.jl index aa65b99..19547e8 100644 --- a/connectors/clients/julia/src/error.jl +++ b/connectors/clients/julia/src/error.jl @@ -102,14 +102,14 @@ struct ProvenanceInvalidError <: VeriSimError message::String end -"""VQL syntax error.""" -struct VqlParseError <: VeriSimError +"""VCL syntax error.""" +struct VclParseError <: VeriSimError query::String message::String end -"""VQL runtime error.""" -struct VqlExecutionError <: VeriSimError +"""VCL runtime error.""" +struct VclExecutionError <: VeriSimError query::String message::String end diff --git a/connectors/clients/julia/src/federation.jl b/connectors/clients/julia/src/federation.jl index 52b7ea8..d004a2a 100644 --- a/connectors/clients/julia/src/federation.jl +++ b/connectors/clients/julia/src/federation.jl @@ -25,7 +25,7 @@ JSON3.StructTypes.StructType(::Type{PeerRegistration}) = JSON3.StructTypes.Struc """ FederatedQueryRequest -Wraps a VQL query intended for federated execution across cluster peers. +Wraps a VCL query intended for federated execution across cluster peers. """ struct FederatedQueryRequest query::String @@ -53,7 +53,7 @@ Result from a single peer in a federated query. struct PeerQueryResult peer_id::String peer_name::String - result::VqlResult + result::VclResult elapsed_ms::Float64 error::Union{String,Nothing} end @@ -109,7 +109,7 @@ end """ federated_query(client, input) -> FederatedQueryResult -Execute a VQL query across one or more federation peers. +Execute a VCL query across one or more federation peers. If `peer_ids` is empty, the query is broadcast to all active peers. Results are aggregated with per-peer timing and error information. diff --git a/connectors/clients/julia/src/types.jl b/connectors/clients/julia/src/types.jl index a9de504..f855873 100644 --- a/connectors/clients/julia/src/types.jl +++ b/connectors/clients/julia/src/types.jl @@ -372,36 +372,36 @@ end JSON3.StructTypes.StructType(::Type{SearchResult}) = JSON3.StructTypes.Struct() # --------------------------------------------------------------------------- -# VQL types +# VCL types # --------------------------------------------------------------------------- """ - VqlResult + VclResult -Result of a VQL query execution, containing columnar data and timing. +Result of a VCL query execution, containing columnar data and timing. """ -struct VqlResult +struct VclResult columns::Vector{String} rows::Vector{Vector{String}} count::Int elapsed_ms::Float64 end -JSON3.StructTypes.StructType(::Type{VqlResult}) = JSON3.StructTypes.Struct() +JSON3.StructTypes.StructType(::Type{VclResult}) = JSON3.StructTypes.Struct() """ - VqlExplanation + VclExplanation -Query execution plan for a VQL statement, showing cost estimates and warnings. +Query execution plan for a VCL statement, showing cost estimates and warnings. """ -struct VqlExplanation +struct VclExplanation query::String plan::String cost::Float64 warnings::Vector{String} end -JSON3.StructTypes.StructType(::Type{VqlExplanation}) = JSON3.StructTypes.Struct() +JSON3.StructTypes.StructType(::Type{VclExplanation}) = JSON3.StructTypes.Struct() # --------------------------------------------------------------------------- # Federation types diff --git a/connectors/clients/julia/src/vql.jl b/connectors/clients/julia/src/vcl.jl similarity index 56% rename from connectors/clients/julia/src/vql.jl rename to connectors/clients/julia/src/vcl.jl index d4a6a56..42578b9 100644 --- a/connectors/clients/julia/src/vql.jl +++ b/connectors/clients/julia/src/vcl.jl @@ -1,18 +1,18 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# VeriSimDB Julia Client — VQL (VeriSimDB Query Language) operations. +# VeriSimDB Julia Client — VCL (VeriSimDB Query Language) operations. # -# VQL is VeriSimDB's native query language for multi-modal queries that span +# VCL is VeriSimDB's native query language for multi-modal queries that span # graph traversals, vector similarity, spatial filters, and temporal constraints # in a single statement. This file provides execution and explain functions. """ - execute_vql(client, query; params=Dict()) -> VqlResult + execute_vcl(client, query; params=Dict()) -> VclResult -Execute a VQL query and return the result set. +Execute a VCL query and return the result set. -VQL queries can combine modalities — for example: +VCL queries can combine modalities — for example: ``` FIND octads WHERE vector_similar(\$embedding, 0.8) AND spatial_within(51.5, -0.1, 10km) @@ -21,46 +21,46 @@ FIND octads WHERE vector_similar(\$embedding, 0.8) # Arguments - `client::Client` — The authenticated client. -- `query::String` — The VQL query string. +- `query::String` — The VCL query string. # Keyword Arguments - `params::Dict{String,String}` — Named parameters for parameterised queries. # Returns -A `VqlResult` containing columns, rows, count, and execution time. +A `VclResult` containing columns, rows, count, and execution time. """ -function execute_vql( +function execute_vcl( client::Client, query::String; params::Dict{String,String}=Dict{String,String}() -)::VqlResult +)::VclResult body = Dict("query" => query, "params" => params) - resp = do_post(client, "/api/v1/vql/execute", body) - return parse_response(VqlResult, resp) + resp = do_post(client, "/api/v1/vcl/execute", body) + return parse_response(VclResult, resp) end """ - explain_vql(client, query; params=Dict()) -> VqlExplanation + explain_vcl(client, query; params=Dict()) -> VclExplanation -Return the query execution plan for a VQL statement without running it. +Return the query execution plan for a VCL statement without running it. Useful for debugging and optimising queries. # Arguments - `client::Client` — The authenticated client. -- `query::String` — The VQL query string. +- `query::String` — The VCL query string. # Keyword Arguments - `params::Dict{String,String}` — Named parameters. # Returns -A `VqlExplanation` containing the plan, estimated cost, and warnings. +A `VclExplanation` containing the plan, estimated cost, and warnings. """ -function explain_vql( +function explain_vcl( client::Client, query::String; params::Dict{String,String}=Dict{String,String}() -)::VqlExplanation +)::VclExplanation body = Dict("query" => query, "params" => params) - resp = do_post(client, "/api/v1/vql/explain", body) - return parse_response(VqlExplanation, resp) + resp = do_post(client, "/api/v1/vcl/explain", body) + return parse_response(VclExplanation, resp) end diff --git a/connectors/clients/rust/src/lib.rs b/connectors/clients/rust/src/lib.rs index 8e54710..e1ba109 100644 --- a/connectors/clients/rust/src/lib.rs +++ b/connectors/clients/rust/src/lib.rs @@ -5,7 +5,7 @@ //! //! A Rust client library for interacting with VeriSimDB — a multi-modal database //! supporting octad entity management, drift detection, provenance tracking, -//! VQL query execution, and federation across distributed instances. +//! VCL query execution, and federation across distributed instances. //! //! ## Quick Start //! @@ -30,7 +30,7 @@ //! - [`search`] — Text, vector, graph-relational, and spatial search operations. //! - [`drift`] — Drift score retrieval and normalization triggers. //! - [`provenance`] — Immutable provenance chain management. -//! - [`vql`] — VeriSim Query Language execution and explain plans. +//! - [`vcl`] — VeriSim Query Language execution and explain plans. //! - [`federation`] — Peer registration and federated cross-instance queries. //! - [`error`] — Error types and the crate-level `Result` alias. @@ -41,6 +41,6 @@ pub mod octad; pub mod search; pub mod drift; pub mod provenance; -pub mod vql; +pub mod vcl; pub mod federation; pub mod error; diff --git a/connectors/clients/rust/src/vql.rs b/connectors/clients/rust/src/vcl.rs similarity index 63% rename from connectors/clients/rust/src/vql.rs rename to connectors/clients/rust/src/vcl.rs index b07da6a..139c118 100644 --- a/connectors/clients/rust/src/vql.rs +++ b/connectors/clients/rust/src/vcl.rs @@ -1,24 +1,24 @@ // SPDX-License-Identifier: MPL-2.0 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -//! VeriSim Query Language (VQL) execution. +//! VeriSim Query Language (VCL) execution. //! -//! VQL is VeriSimDB's native query language, supporting SQL-like syntax extended +//! VCL is VeriSimDB's native query language, supporting SQL-like syntax extended //! with multi-modal operations (vector similarity, graph traversal, spatial //! predicates, drift thresholds, etc.). This module provides methods to execute -//! VQL statements and retrieve explain / query plans. +//! VCL statements and retrieve explain / query plans. use serde::{Deserialize, Serialize}; use crate::client::VeriSimClient; use crate::error::Result; -/// Response from a VQL query execution or explain request. +/// Response from a VCL query execution or explain request. #[derive(Debug, Clone, Serialize, Deserialize)] -pub struct VqlResponse { +pub struct VclResponse { /// Whether the query executed successfully. pub success: bool, - /// The type of VQL statement ("SELECT", "INSERT", "UPDATE", "DELETE", "EXPLAIN", etc.). + /// The type of VCL statement ("SELECT", "INSERT", "UPDATE", "DELETE", "EXPLAIN", etc.). pub statement_type: String, /// Number of rows affected or returned. pub row_count: usize, @@ -28,45 +28,45 @@ pub struct VqlResponse { pub message: Option, } -/// Internal request body for VQL execution. +/// Internal request body for VCL execution. #[derive(Debug, Serialize)] -struct VqlRequest { +struct VclRequest { query: String, } impl VeriSimClient { - /// Execute a VQL statement against the VeriSimDB instance. + /// Execute a VCL statement against the VeriSimDB instance. /// /// Supports SELECT, INSERT, UPDATE, DELETE, and VeriSimDB-specific /// statements like `DRIFT CHECK`, `NORMALIZE`, and `FEDERATE`. /// /// # Arguments /// - /// * `query` — The VQL statement string. + /// * `query` — The VCL statement string. /// /// # Errors /// /// Returns [`VeriSimError::Server`] if the query has syntax errors or /// the server rejects it for semantic reasons. - pub async fn execute_vql(&self, query: &str) -> Result { - let body = VqlRequest { + pub async fn execute_vcl(&self, query: &str) -> Result { + let body = VclRequest { query: query.to_owned(), }; - self.post("/api/v1/vql/execute", &body).await + self.post("/api/v1/vcl/execute", &body).await } - /// Request an explain / query plan for a VQL statement without executing it. + /// Request an explain / query plan for a VCL statement without executing it. /// /// Useful for understanding which modalities, indices, and federation peers /// would be involved in a query. /// /// # Arguments /// - /// * `query` — The VQL statement string to explain. - pub async fn explain_vql(&self, query: &str) -> Result { - let body = VqlRequest { + /// * `query` — The VCL statement string to explain. + pub async fn explain_vcl(&self, query: &str) -> Result { + let body = VclRequest { query: query.to_owned(), }; - self.post("/api/v1/vql/explain", &body).await + self.post("/api/v1/vcl/explain", &body).await } } diff --git a/connectors/clients/zig/README.adoc b/connectors/clients/zig/README.adoc index ec0e503..22c999d 100644 --- a/connectors/clients/zig/README.adoc +++ b/connectors/clients/zig/README.adoc @@ -27,7 +27,7 @@ rather than via a maintained per-language SDK. | `src/drift.zig` | Drift: `score / status / normalize`. | `src/provenance.zig` | Provenance: `chain / record / verify`. | `src/search.zig` | Multi-modal search: text / vector / spatial / nearest / related. -| `src/vql.zig` | VCL: `execute / explain`. +| `src/vcl.zig` | VCL: `execute / explain`. | `src/federation.zig` | Federation: `registerPeer / listPeers / query`. |=== diff --git a/connectors/clients/zig/src/error.zig b/connectors/clients/zig/src/error.zig index 0236bd5..8f35410 100644 --- a/connectors/clients/zig/src/error.zig +++ b/connectors/clients/zig/src/error.zig @@ -24,8 +24,8 @@ pub const VeriSimErrorCode = enum { modality_unavailable, drift_computation, provenance_invalid, - vql_parse_error, - vql_execution_error, + vcl_parse_error, + vcl_execution_error, federation_error, // Client-side connection_error, @@ -49,8 +49,8 @@ pub const VeriSimErrorCode = enum { .{ "MODALITY_UNAVAILABLE", .modality_unavailable }, .{ "DRIFT_COMPUTATION", .drift_computation }, .{ "PROVENANCE_INVALID", .provenance_invalid }, - .{ "VQL_PARSE_ERROR", .vql_parse_error }, - .{ "VQL_EXECUTION_ERROR", .vql_execution_error }, + .{ "VCL_PARSE_ERROR", .vcl_parse_error }, + .{ "VCL_EXECUTION_ERROR", .vcl_execution_error }, .{ "FEDERATION_ERROR", .federation_error }, }; inline for (map) |entry| { diff --git a/connectors/clients/zig/src/federation.zig b/connectors/clients/zig/src/federation.zig index 7a98018..61910fb 100644 --- a/connectors/clients/zig/src/federation.zig +++ b/connectors/clients/zig/src/federation.zig @@ -20,7 +20,7 @@ pub const FederatedQueryRequest = struct { pub const PeerQueryResult = struct { peer_id: []const u8, peer_name: []const u8, - result: types.VqlResult, + result: types.VclResult, elapsed_ms: f64 = 0.0, @"error": ?[]const u8 = null, }; diff --git a/connectors/clients/zig/src/root.zig b/connectors/clients/zig/src/root.zig index d6f0cd0..2f7c18c 100644 --- a/connectors/clients/zig/src/root.zig +++ b/connectors/clients/zig/src/root.zig @@ -19,7 +19,7 @@ pub const octad = @import("octad.zig"); pub const drift = @import("drift.zig"); pub const provenance = @import("provenance.zig"); pub const search = @import("search.zig"); -pub const vql = @import("vql.zig"); +pub const vcl = @import("vcl.zig"); pub const federation = @import("federation.zig"); pub const Client = @import("client.zig").Client; @@ -40,8 +40,8 @@ pub const ProvenanceEvent = types.ProvenanceEvent; pub const ProvenanceChain = types.ProvenanceChain; pub const PaginatedResponse = types.PaginatedResponse; pub const SearchResult = types.SearchResult; -pub const VqlResult = types.VqlResult; -pub const VqlExplanation = types.VqlExplanation; +pub const VclResult = types.VclResult; +pub const VclExplanation = types.VclExplanation; pub const FederationPeer = types.FederationPeer; test { @@ -53,6 +53,6 @@ test { _ = @import("drift.zig"); _ = @import("provenance.zig"); _ = @import("search.zig"); - _ = @import("vql.zig"); + _ = @import("vcl.zig"); _ = @import("federation.zig"); } diff --git a/connectors/clients/zig/src/types.zig b/connectors/clients/zig/src/types.zig index 25f4d6b..c0be3b3 100644 --- a/connectors/clients/zig/src/types.zig +++ b/connectors/clients/zig/src/types.zig @@ -152,14 +152,14 @@ pub const SearchResult = struct { score: f64 = 0.0, }; -pub const VqlResult = struct { +pub const VclResult = struct { columns: []const []const u8, rows: []const []const []const u8, count: u64 = 0, elapsed_ms: f64 = 0.0, }; -pub const VqlExplanation = struct { +pub const VclExplanation = struct { query: []const u8, plan: []const u8, cost: f64 = 0.0, diff --git a/connectors/clients/zig/src/vql.zig b/connectors/clients/zig/src/vcl.zig similarity index 75% rename from connectors/clients/zig/src/vql.zig rename to connectors/clients/zig/src/vcl.zig index 7d3ba20..8a2cc12 100644 --- a/connectors/clients/zig/src/vql.zig +++ b/connectors/clients/zig/src/vcl.zig @@ -1,13 +1,13 @@ // SPDX-License-Identifier: MPL-2.0 -// VeriSimDB Zig Client — VQL execution and explain. +// VeriSimDB Zig Client — VCL execution and explain. const std = @import("std"); const Client = @import("client.zig").Client; const types = @import("types.zig"); const errors = @import("error.zig"); -pub const ParsedResult = std.json.Parsed(types.VqlResult); -pub const ParsedExplanation = std.json.Parsed(types.VqlExplanation); +pub const ParsedResult = std.json.Parsed(types.VclResult); +pub const ParsedExplanation = std.json.Parsed(types.VclExplanation); pub const Request = struct { query: []const u8, @@ -33,15 +33,15 @@ fn decode( pub fn execute(client: *Client, query: []const u8) !ParsedResult { const body = try std.fmt.allocPrint(client.allocator, "{{\"query\":\"{s}\"}}", .{query}); defer client.allocator.free(body); - const resp = try client.doPost("/api/v1/vql/execute", body); + const resp = try client.doPost("/api/v1/vcl/execute", body); defer resp.deinit(client.allocator); - return decode(types.VqlResult, client.allocator, resp.body, resp.status); + return decode(types.VclResult, client.allocator, resp.body, resp.status); } pub fn explain(client: *Client, query: []const u8) !ParsedExplanation { const body = try std.fmt.allocPrint(client.allocator, "{{\"query\":\"{s}\"}}", .{query}); defer client.allocator.free(body); - const resp = try client.doPost("/api/v1/vql/explain", body); + const resp = try client.doPost("/api/v1/vcl/explain", body); defer resp.deinit(client.allocator); - return decode(types.VqlExplanation, client.allocator, resp.body, resp.status); + return decode(types.VclExplanation, client.allocator, resp.body, resp.status); }