Skip to main content

arcadedb_protocol/client/
execute.rs

1//! Write and query-language execution — the `execute_command` RPC surface:
2//! SQL commands, bound parameters, and the Cypher variants.
3
4use super::*;
5
6impl ArcadeDbClient {
7    /// Execute a command in the given query language ("sql" or "cypher").
8    ///
9    /// Returns the server response including affected records and write stats.
10    pub async fn execute_language(
11        &self,
12        database: &str,
13        language: &str,
14        command: &str,
15    ) -> Result<ExecuteCommandResponse> {
16        let req = tonic::Request::new(ExecuteCommandRequest {
17            database: database.into(),
18            command: command.into(),
19            credentials: Some(self.auth.creds.clone()),
20            language: language.into(),
21            return_rows: true,
22            ..Default::default()
23        });
24
25        let resp = self
26            .data
27            .clone()
28            .execute_command(self.add_auth_headers(req))
29            .await
30            .map_err(|e| map_rpc_error("execute command", command, e))?
31            .into_inner();
32
33        if !resp.success {
34            return Err(command_failed(
35                "execute command",
36                resp.message,
37                resp.affected_records,
38            ));
39        }
40
41        Ok(resp)
42    }
43
44    /// Execute a SQL command (DDL, INSERT, UPDATE, DELETE).
45    ///
46    /// Returns the server response including affected records and write stats.
47    pub async fn execute(&self, database: &str, command: &str) -> Result<ExecuteCommandResponse> {
48        self.execute_with_values(database, command, std::collections::HashMap::new())
49            .await
50    }
51
52    /// [`execute`](Self::execute) with bound `:name` parameters — the
53    /// command-RPC analogue of [`query_with_values`](Self::query_with_values).
54    /// Prefer this whenever the command references caller-supplied values
55    /// (user names, urls, ids): no literal escaping, no injection surface.
56    /// Build parameter values with [`Params`](crate::Params) (e.g. the
57    /// [`params!`](crate::params!) macro) or a `RecordEncode` DTO's
58    /// [`ToGrpcRecord::to_param_map`](crate::ToGrpcRecord::to_param_map).
59    pub async fn execute_with_values(
60        &self,
61        database: &str,
62        command: &str,
63        parameters: impl Into<crate::encode::Params>,
64    ) -> Result<ExecuteCommandResponse> {
65        let parameters = parameters.into();
66        let req = tonic::Request::new(ExecuteCommandRequest {
67            database: database.into(),
68            command: command.into(),
69            parameters: parameters.0,
70            credentials: Some(self.auth.creds.clone()),
71            language: "sql".into(),
72            return_rows: true,
73            ..Default::default()
74        });
75
76        let resp = self
77            .data
78            .clone()
79            .execute_command(self.add_auth_headers(req))
80            .await
81            .map_err(|e| map_rpc_error("execute command", command, e))?
82            .into_inner();
83
84        if !resp.success {
85            return Err(command_failed(
86                "execute command",
87                resp.message,
88                resp.affected_records,
89            ));
90        }
91
92        Ok(resp)
93    }
94
95    /// Execute a Cypher read query (MATCH + RETURN, etc.).
96    ///
97    /// Uses the streaming query RPC with language="cypher".
98    pub async fn cypher_query(&self, database: &str, query: &str) -> Result<QueryResult> {
99        let req = tonic::Request::new(ExecuteQueryRequest {
100            database: database.into(),
101            query: query.into(),
102            credentials: Some(self.auth.creds.clone()),
103            language: "cypher".into(),
104            ..Default::default()
105        });
106
107        let resp = self
108            .data
109            .clone()
110            .execute_query(self.add_auth_headers(req))
111            .await
112            .map_err(|e| map_rpc_error("cypher query", query, e))?
113            .into_inner();
114
115        let mut records = Vec::with_capacity(resp.results.iter().map(|qr| qr.records.len()).sum());
116        records.extend(resp.results.into_iter().flat_map(|qr| qr.records));
117
118        Ok(QueryResult {
119            records,
120            execution_time_ms: resp.execution_time_ms,
121        })
122    }
123
124    /// Execute a Cypher write command (MATCH + SET, etc.).
125    ///
126    /// Uses the execute_command RPC with language set to "opencypher"
127    /// (the variant that ArcadeDB accepts for write operations).
128    pub async fn cypher_execute(
129        &self,
130        database: &str,
131        command: &str,
132    ) -> Result<ExecuteCommandResponse> {
133        self.execute_language(database, "opencypher", command).await
134    }
135}