diff --git a/crates/core/README.md b/crates/core/README.md index dbfd6c4..91c9ed4 100644 --- a/crates/core/README.md +++ b/crates/core/README.md @@ -1998,7 +1998,21 @@ qn.kvstore.delete_list("my-list").await?; ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. + +**Parameters**: none. + +**Returns**: `Vec`, each with `id` and `display_name`. + +```rust +// Rust +let clusters = qn.sql.list_clusters().await?; +println!("{:?}", clusters.iter().map(|c| &c.id).collect::>()); +``` ##### `query` diff --git a/crates/core/examples/sql.rs b/crates/core/examples/sql.rs index ff6cf3b..07323d3 100644 --- a/crates/core/examples/sql.rs +++ b/crates/core/examples/sql.rs @@ -8,6 +8,24 @@ async fn main() { let config = SdkFullConfig::from_env().expect("Config from env failed"); let qn = QuicknodeSdk::new(&config).expect("sdk failed to initialize"); + // ── Clusters ────────────────────────────────────────────────────────────── + + let clusters = qn.sql.list_clusters().await.expect("list_clusters failed"); + println!( + "clusters: {:?}", + clusters.iter().map(|c| &c.id).collect::>() + ); + assert!( + clusters + .iter() + .all(|c| !c.id.is_empty() && !c.display_name.is_empty()), + "every cluster has an id and a display name" + ); + assert!( + clusters.iter().any(|c| c.id == CLUSTER_ID), + "{CLUSTER_ID} is in the cluster list" + ); + // ── Query ───────────────────────────────────────────────────────────────── let params = QueryParams { diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 76774f9..4eb5057 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -56,7 +56,7 @@ pub use rpc::{ pub use rpc::{ChannelState, ChannelStatus}; pub use sql::{ ChainSchema, ColumnMeta, ColumnSchema, QueryParams, QueryResponse, QueryStatistics, - SqlApiClient, TableSchema, + SqlApiClient, SqlCluster, TableSchema, }; use reqwest::header::{HeaderMap, HeaderName, HeaderValue}; @@ -285,8 +285,9 @@ pub struct QuicknodeSdk { /// Key-Value Store client: manages sets (single values) and lists /// (ordered collections) under string keys. pub kvstore: kvstore::KvStoreApiClient, - /// SQL Explorer client: executes SQL queries against indexed blockchain - /// data and fetches the database schema. + /// SQL Explorer client: lists the available clusters, executes SQL + /// queries against indexed blockchain data, and fetches the database + /// schema. pub sql: sql::SqlApiClient, /// JSON-RPC client: makes on-chain calls against the account's Tooling /// Access endpoint using short-lived session JWTs. diff --git a/crates/core/src/sql/mod.rs b/crates/core/src/sql/mod.rs index 56fe690..812f34a 100644 --- a/crates/core/src/sql/mod.rs +++ b/crates/core/src/sql/mod.rs @@ -32,6 +32,31 @@ impl ResolvedSqlConfig { } } +// ── Catalog types ────────────────────────────────────────────────────────── + +/// A cluster that SQL queries can target, as returned by `list_clusters`. +#[cfg_attr(feature = "python", gen_stub_pyclass)] +#[cfg_attr(feature = "python", pyclass(get_all, set_all))] +#[cfg_attr(feature = "node", napi(object))] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct SqlCluster { + /// Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + /// `cluster_id` to `query` and `get_schema`. + pub id: String, + /// Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + pub display_name: String, +} + +#[cfg(feature = "python")] +#[gen_stub_pymethods] +#[pymethods] +impl SqlCluster { + #[new] + pub fn new(id: String, display_name: String) -> Self { + Self { id, display_name } + } +} + // ── Request types ────────────────────────────────────────────────────────── /// Parameters for `query`. @@ -232,8 +257,9 @@ impl ChainSchema { // ── Client ───────────────────────────────────────────────────────────────── -/// Client for the Quicknode SQL Explorer. Executes SQL queries against indexed -/// blockchain data and fetches the database schema. +/// Client for the Quicknode SQL Explorer. Lists the available clusters, +/// executes SQL queries against indexed blockchain data, and fetches the +/// database schema. #[derive(Debug, Clone)] pub struct SqlApiClient { config: SdkConfig, @@ -244,6 +270,24 @@ impl SqlApiClient { Self { config } } + /// Lists the clusters available to query. + pub async fn list_clusters(&self) -> Result, SdkError> { + let url = self.config.sql().base_url.join("clusters")?; + let resp = self + .config + .http_client() + .get(url) + .send() + .await + .map_err(SdkError::Http)?; + let status = resp.status(); + let body = resp.text().await.map_err(SdkError::Http)?; + if !status.is_success() { + return Err(SdkError::Api { status, body }); + } + serde_json::from_str(&body).map_err(|source| SdkError::Decode { source, body }) + } + /// Executes a SQL query against the given cluster and returns the result /// set. pub async fn query(&self, params: &QueryParams) -> Result { @@ -295,7 +339,7 @@ impl SqlApiClient { mod tests { use super::*; use crate::{QuicknodeSdk, SdkFullConfig, SqlConfig}; - use wiremock::matchers::{body_json, method, path}; + use wiremock::matchers::{body_json, header, method, path}; use wiremock::{Mock, MockServer, ResponseTemplate}; fn make_sdk(base_url: String) -> QuicknodeSdk { @@ -321,6 +365,55 @@ mod tests { } } + // ── list_clusters ──────────────────────────────────────────────────────── + + #[tokio::test] + async fn list_clusters_success() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + .and(header("x-api-key", "test-key")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([ + {"id": "hyperliquid-core-mainnet", "display_name": "Hyperliquid (HyperCore)"}, + {"id": "solana-mainnet", "display_name": "Solana"} + ]))) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let clusters = sdk.sql.list_clusters().await.unwrap(); + assert_eq!(clusters.len(), 2); + assert_eq!(clusters[0].id, "hyperliquid-core-mainnet"); + assert_eq!(clusters[0].display_name, "Hyperliquid (HyperCore)"); + assert_eq!(clusters[1].id, "solana-mainnet"); + assert_eq!(clusters[1].display_name, "Solana"); + } + + #[tokio::test] + async fn list_clusters_api_error() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error")) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let err = sdk.sql.list_clusters().await.unwrap_err(); + assert!(matches!(err, SdkError::Api { .. })); + } + + #[tokio::test] + async fn list_clusters_decode_error() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + .respond_with(ResponseTemplate::new(200).set_body_string("not json")) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let err = sdk.sql.list_clusters().await.unwrap_err(); + assert!(matches!(err, SdkError::Decode { .. })); + } + // ── query ────────────────────────────────────────────────────────────── #[tokio::test] diff --git a/crates/node/src/lib.rs b/crates/node/src/lib.rs index db6a573..1bd1ea5 100644 --- a/crates/node/src/lib.rs +++ b/crates/node/src/lib.rs @@ -1923,6 +1923,15 @@ pub struct SqlApiClient { #[napi] impl SqlApiClient { + /// Lists the clusters available to query. + #[napi] + pub async fn list_clusters(&self) -> Result> { + self.inner + .list_clusters() + .await + .map_err(errors::map_sdk_err) + } + /// Executes a SQL query against the given cluster and returns the result set. #[napi] pub async fn query(&self, query: String, cluster_id: String) -> Result { diff --git a/crates/python/src/lib.rs b/crates/python/src/lib.rs index 72fb095..ebad514 100644 --- a/crates/python/src/lib.rs +++ b/crates/python/src/lib.rs @@ -3349,6 +3349,17 @@ pub struct SqlApiClient { #[gen_stub_pymethods] #[pymethods] impl SqlApiClient { + /// Lists the clusters available to query. + #[gen_stub(override_return_type( + type_repr = "typing.Coroutine[typing.Any, typing.Any, list[SqlCluster]]" + ))] + fn list_clusters<'py>(&self, py: Python<'py>) -> PyResult> { + let client = self.inner.clone(); + pyo3_async_runtimes::tokio::future_into_py(py, async move { + client.list_clusters().await.map_err(errors::map_sdk_err) + }) + } + /// Executes a SQL query against the given cluster and returns the result /// set. #[pyo3(signature = (query, cluster_id))] @@ -4230,6 +4241,7 @@ fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_class::()?; // sql m.add_class::()?; + m.add_class::()?; m.add_class::()?; m.add_class::()?; m.add_class::()?; diff --git a/crates/ruby/src/lib.rs b/crates/ruby/src/lib.rs index 6345a31..820c4f7 100644 --- a/crates/ruby/src/lib.rs +++ b/crates/ruby/src/lib.rs @@ -2494,6 +2494,14 @@ pub struct SqlApiClient { #[allow(clippy::needless_pass_by_value)] impl SqlApiClient { + fn list_clusters(&self) -> Result { + let client = self.inner.clone(); + runtime() + .block_on(client.list_clusters()) + .map_err(map_err) + .and_then(to_ruby) + } + fn query(&self, opts: RHash) -> Result { validate_keys(&opts, &["query", "cluster_id"])?; let client = self.inner.clone(); @@ -3341,6 +3349,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> { // ── Sql ─────────────────────────────────────────────────── let sql = native.define_class("Sql", ruby.class_object())?; + sql.define_method("list_clusters", method!(SqlApiClient::list_clusters, 0))?; sql.define_method("query", method!(SqlApiClient::query, 1))?; sql.define_method("get_schema", method!(SqlApiClient::get_schema, 1))?; diff --git a/npm/README.md b/npm/README.md index b529298..eec33f2 100644 --- a/npm/README.md +++ b/npm/README.md @@ -1839,7 +1839,21 @@ await qn.kvstore.deleteList("my-list"); ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` / `listClusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` / `clusterId` for `query` and `getSchema`. + +**Parameters**: none. + +**Returns**: an array of `SqlCluster`, each with `id` and `display_name` / `displayName`. + +```typescript +// Node.js +const clusters = await qn.sql.listClusters(); +console.log(clusters.map((c) => c.id)); +``` ##### `query` diff --git a/npm/examples/sql.ts b/npm/examples/sql.ts index a72b169..faa3efd 100644 --- a/npm/examples/sql.ts +++ b/npm/examples/sql.ts @@ -5,6 +5,16 @@ const CLUSTER_ID = "hyperliquid-core-mainnet"; async function main() { const qn = QuicknodeSdk.fromEnv(); + // Clusters + const clusters = await qn.sql.listClusters(); + console.log(`clusters: ${clusters.map((c) => c.id).join(", ")}`); + if (!clusters.every((c) => c.id && c.displayName)) { + throw new Error("every cluster must have an id and a displayName"); + } + if (!clusters.some((c) => c.id === CLUSTER_ID)) { + throw new Error(`${CLUSTER_ID} not in cluster list`); + } + // Query const resp = await qn.sql.query( "SELECT toDateTime(block_time) AS time, action_type, user " + diff --git a/npm/index.d.ts b/npm/index.d.ts index 003bb03..1eb2915 100644 --- a/npm/index.d.ts +++ b/npm/index.d.ts @@ -2337,6 +2337,17 @@ export interface SolanaWalletFilterTemplate { accounts: Array } +/** A cluster that SQL queries can target, as returned by `list_clusters`. */ +export interface SqlCluster { + /** + * Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + * `cluster_id` to `query` and `get_schema`. + */ + id: string + /** Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). */ + displayName: string +} + export interface SqlConfig { baseUrl?: string } @@ -3647,8 +3658,9 @@ export declare class RpcApiClient { gatewayBuyCredits(session: any, network: string): Promise /** * Requests testnet tokens from the x402 faucet. Resolves to the funding - * transaction `{ accountId, transactionHash }` — NOT a balance; call - * `gatewayCredits` afterwards for that. Allowed once per account. + * transfer metadata containing either `transferId` or `transactionHash`. + * The former is asynchronous Circle settlement; the latter is a direct + * on-chain transfer. This is not a balance; call `gatewayCredits` for that. */ gatewayDrip(session: any): Promise /** @@ -3698,6 +3710,8 @@ export declare class RpcApiClient { } export declare class SqlApiClient { + /** Lists the clusters available to query. */ + listClusters(): Promise> /** Executes a SQL query against the given cluster and returns the result set. */ query(query: string, clusterId: string): Promise /** diff --git a/npm/sdk.d.ts b/npm/sdk.d.ts index 69bc004..effd94f 100644 --- a/npm/sdk.d.ts +++ b/npm/sdk.d.ts @@ -17,6 +17,7 @@ import { HyperliquidWalletEventsFilterTemplate, StellarWalletTransactionsFilterTemplate, RpcApiClient, + SqlCluster, } from "./index"; // Stream destination attributes (input). The inner key is `attributes` rather @@ -410,6 +411,7 @@ export type { // sql SqlConfig, SqlApiClient, + SqlCluster, QueryResponseNode, ColumnMetaNode, QueryStatisticsNode, @@ -572,6 +574,7 @@ export interface QueryResult extends Omit { } export interface SqlApiClientTyped { + listClusters(): Promise; query(query: string, clusterId: string): Promise; getSchema(clusterId: string): Promise; } diff --git a/python/README.md b/python/README.md index 54b2b5a..76cb16e 100644 --- a/python/README.md +++ b/python/README.md @@ -1834,7 +1834,21 @@ await qn.kvstore.delete_list("my-list") ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. + +**Parameters**: none. + +**Returns**: `list[SqlCluster]`, each with `id` and `display_name`. + +```python +# Python +clusters = await qn.sql.list_clusters() +print([c.id for c in clusters]) +``` ##### `query` diff --git a/python/examples/sql.py b/python/examples/sql.py index 28f0e3c..7e636c1 100644 --- a/python/examples/sql.py +++ b/python/examples/sql.py @@ -7,6 +7,12 @@ async def main(): qn = QuicknodeSdk.from_env() + # Clusters + clusters = await qn.sql.list_clusters() + print(f"clusters: {[c.id for c in clusters]}") + assert all(c.id and c.display_name for c in clusters) + assert any(c.id == CLUSTER_ID for c in clusters), f"{CLUSTER_ID} not in cluster list" + # Query resp = await qn.sql.query( query=( diff --git a/python/quicknode_sdk/__init__.py b/python/quicknode_sdk/__init__.py index cdaf331..60c3516 100644 --- a/python/quicknode_sdk/__init__.py +++ b/python/quicknode_sdk/__init__.py @@ -221,6 +221,7 @@ GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -532,6 +533,7 @@ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/python/quicknode_sdk/__init__.pyi b/python/quicknode_sdk/__init__.pyi index b1e7b8b..244639a 100644 --- a/python/quicknode_sdk/__init__.pyi +++ b/python/quicknode_sdk/__init__.pyi @@ -223,6 +223,7 @@ from quicknode_sdk._core import ( GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -550,6 +551,7 @@ __all__ = [ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/python/quicknode_sdk/_core/__init__.pyi b/python/quicknode_sdk/_core/__init__.pyi index 7a4a11b..39fd756 100644 --- a/python/quicknode_sdk/_core/__init__.pyi +++ b/python/quicknode_sdk/_core/__init__.pyi @@ -234,6 +234,7 @@ __all__ = [ "SolanaWalletFilterByListTemplate", "SolanaWalletFilterTemplate", "SqlApiClient", + "SqlCluster", "SqlConfig", "StellarWalletTransactionsFilterArgs", "StellarWalletTransactionsFilterByListArgs", @@ -1837,7 +1838,7 @@ class CachedToken: A minted session JWT plus the endpoint it authenticates against and its wall-clock expiry. This is the unit cached by the RPC client and the unit a host persists between processes (e.g. the CLI's on-disk token cache). - + `exp_unix` is the JWT `exp` claim (unix seconds), used directly so it survives a process restart (unlike a monotonic `Instant`). """ @@ -5793,7 +5794,7 @@ class HttpConfig: def headers(self) -> typing.Optional[builtins.dict[builtins.str, builtins.str]]: r""" Custom HTTP headers added to every outbound request. - + **These headers OVERRIDE any SDK-managed header with the same name**, including `User-Agent`, `x-api-key`, `Accept`, and `Content-Type`. Header names are matched case-insensitively. Use this to override the @@ -5803,7 +5804,7 @@ class HttpConfig: def headers(self, value: typing.Optional[builtins.dict[builtins.str, builtins.str]]) -> None: r""" Custom HTTP headers added to every outbound request. - + **These headers OVERRIDE any SDK-managed header with the same name**, including `User-Agent`, `x-api-key`, `Accept`, and `Content-Type`. Header names are matched case-insensitively. Use this to override the @@ -7158,7 +7159,7 @@ class PaymentConfig: boundary. The private `key` field stays readable to the caller, but the SDK's own `Debug` redacts it (below) so an SDK log line or panic can't leak it. - + **Do not log your own `PaymentConfig`** — `println!("{config:?}")` on the derived-Debug *binding* object (napi/pyclass/hash) still shows the raw key. Only the SDK's internal rendering is redacted. @@ -7665,7 +7666,7 @@ class RpcApiClient: and defaults to `[]`. `network` selects a chain on the multichain endpoint (a key in the seeded network map, e.g. `"solana-mainnet"`); omit for the endpoint's default network. - + `endpoint_url` sends this call to a custom HTTP URL instead, bypassing the Tooling Access endpoint and the session JWT (no Authorization header is attached). It overrides the client-wide `RpcConfig.endpoint_url` @@ -7724,8 +7725,8 @@ class RpcApiClient: def gateway_drip(self, session: typing.Any) -> typing.Coroutine[typing.Any, typing.Any, typing.Any]: r""" Requests testnet tokens from the x402 faucet. Returns the funding - transaction as a dict `{account_id, transaction_hash}` — NOT a balance; - call `gateway_credits` afterwards for that. Allowed once per account. + transfer metadata as a dict. Circle-backed responses contain + `transfer_id`; direct transfers contain `transaction_hash`. """ def gateway_drawdown_call(self, method: builtins.str, session: typing.Any, network: builtins.str, params: typing.Optional[typing.Any] = None) -> typing.Coroutine[typing.Any, typing.Any, typing.Any]: r""" @@ -7739,7 +7740,7 @@ class RpcApiClient: decimal string) into the escrow. Returns the channel state dict — persist it; the gateway has no read-only channel endpoint, so a lost record means opening a new channel. Moves real funds; single-attempt. - + Takes no network: the channel is scoped by the configured pay network and asset, so one channel funds calls to every supported network. """ @@ -7758,7 +7759,7 @@ class RpcApiClient: r""" Fetches the gateway's view of the channel as a dict `{channel_id, accepted_cumulative, spent}` (amounts are decimal strings). - + **This costs one request unit** and advances the voucher by `per_call`, exactly like a session call — persist the advanced `cumulative_spent`. Raises `PaymentUnsupportedError` before any network I/O when the channel @@ -8283,6 +8284,10 @@ class SolanaWalletFilterTemplate: @typing.final class SqlApiClient: + def list_clusters(self) -> typing.Coroutine[typing.Any, typing.Any, list[SqlCluster]]: + r""" + Lists the clusters available to query. + """ def query(self, query: builtins.str, cluster_id: builtins.str) -> typing.Coroutine[typing.Any, typing.Any, QueryResponse]: r""" Executes a SQL query against the given cluster and returns the result @@ -8294,6 +8299,35 @@ class SqlApiClient: columns, types, sort keys, and partition strategies. """ +@typing.final +class SqlCluster: + r""" + A cluster that SQL queries can target, as returned by `list_clusters`. + """ + @property + def id(self) -> builtins.str: + r""" + Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + `cluster_id` to `query` and `get_schema`. + """ + @id.setter + def id(self, value: builtins.str) -> None: + r""" + Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + `cluster_id` to `query` and `get_schema`. + """ + @property + def display_name(self) -> builtins.str: + r""" + Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + """ + @display_name.setter + def display_name(self, value: builtins.str) -> None: + r""" + Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + """ + def __new__(cls, id: builtins.str, display_name: builtins.str) -> SqlCluster: ... + @typing.final class SqlConfig: @property diff --git a/python/quicknode_sdk/init_manual_override.pyi b/python/quicknode_sdk/init_manual_override.pyi index b1e7b8b..244639a 100644 --- a/python/quicknode_sdk/init_manual_override.pyi +++ b/python/quicknode_sdk/init_manual_override.pyi @@ -223,6 +223,7 @@ from quicknode_sdk._core import ( GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -550,6 +551,7 @@ __all__ = [ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/ruby/README.md b/ruby/README.md index 4e32ff4..54545fb 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -1847,7 +1847,21 @@ qn.kvstore.delete_list(key: "my-list") ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id:` for `query` and `get_schema`. + +**Parameters**: none. + +**Returns** an Array of Hashes, each with `id` and `display_name`. + +```ruby +# Ruby +clusters = qn.sql.list_clusters +puts clusters.map { |c| c[:id] } +``` ##### `query` diff --git a/ruby/examples/sql.rb b/ruby/examples/sql.rb index dd97a26..5911185 100644 --- a/ruby/examples/sql.rb +++ b/ruby/examples/sql.rb @@ -4,6 +4,12 @@ qn = QuicknodeSdk::SDK.from_env +# Clusters +clusters = qn.sql.list_clusters +puts "clusters: #{clusters.map { |c| c[:id] }.join(', ')}" +raise "every cluster must have an id and a display_name" unless clusters.all? { |c| c[:id] && c[:display_name] } +raise "#{CLUSTER_ID} not in cluster list" unless clusters.any? { |c| c[:id] == CLUSTER_ID } + # Query resp = qn.sql.query( query: "SELECT toDateTime(block_time) AS time, action_type, user " \ diff --git a/ruby/sig/quicknode_sdk.rbs b/ruby/sig/quicknode_sdk.rbs index 8d610a8..cd20a36 100644 --- a/ruby/sig/quicknode_sdk.rbs +++ b/ruby/sig/quicknode_sdk.rbs @@ -242,6 +242,7 @@ module QuicknodeSdk class Sql def initialize: (untyped native) -> void + def list_clusters: () -> untyped def query: (query: String, cluster_id: String) -> untyped def get_schema: (cluster_id: String) -> untyped end