Influxdata
/
influxdb
mirror of https://github.com/influxdata/influxdb.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Improve documentation on query API (#7520) 

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
pull/24376/head
Andrew Lamb 2023-04-12 11:53:42 -04:00 committed by GitHub
parent 7dd221aee0
commit f3de4e39f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 51 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
service_grpc_flight/src/request.rs
View File

@ -24,11 +24,57 @@ pub enum Error {
} }
pub type Result<T, E = Error> = std::result::Result<T, E>; pub type Result<T, E = Error> = std::result::Result<T, E>;
/// This is the structure of the opaque tickets` used for requests to /// Request structure of the "opaque" tickets used for IOx Arrow
/// IOx Flight DoGet endpoint /// Flight DoGet endpoint.
/// ///
/// This structure encapsulates the deserialization and serializion /// This structure encapsulates the deserialization and serializion
/// logic for these requests /// logic for these requests. The protocol is described in more
/// detail on [`FlightService`](crate::FlightService).
///
/// # Ticket Format
///
/// Tickets are encoded in one of two formats:
///
/// 1. Protobuf: as a [ReadInfo](proto::ReadInfo) wrapped as a "Any"
/// message and encoded using binary encoding
///
/// 2. JSON: formatted as below.
///
/// ## Known clients use the JSON encoding
///
/// - <https://github.com/influxdata/influxdb-iox-client-go/commit/2e7a3b0bd47caab7f1a31a1bbe0ff54aa9486b7b>
/// - <https://github.com/influxdata/influxdb-iox-client-go/commit/52f1a1b8d5bb8cc8dc2fe825f4da630ad0b9167c>
///
/// ## Example JSON Ticket format
///
/// This runs the SQL "SELECT 1" in namespace `my_db`
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SELECT 1;"
/// }
/// ```
///
/// This is the same as the example above, but has an explicit query language
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SELECT 1;"
/// "query_type": "sql"
/// }
/// ```
///
/// This runs the 'SHOW DATABASES' InfluxQL command (the `sql_query` field name is misleading)
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SHOW DATABASES;"
/// "query_type": "influxql"
/// }
/// ```
#[derive(Debug, PartialEq, Clone)] #[derive(Debug, PartialEq, Clone)]
pub struct IoxGetRequest { pub struct IoxGetRequest {
namespace_name: String, namespace_name: String,
@ -130,40 +176,7 @@ impl IoxGetRequest {
}) })
} }
/// Some clients still use an older form of ticket encoding, JSON tickets /// See comments on [`IoxGetRequest`] for details of this format
///
/// - <https://github.com/influxdata/influxdb-iox-client-go/commit/2e7a3b0bd47caab7f1a31a1bbe0ff54aa9486b7b>
/// - <https://github.com/influxdata/influxdb-iox-client-go/commit/52f1a1b8d5bb8cc8dc2fe825f4da630ad0b9167c>
///
/// # Example JSON format
/// This runs the SQL "SELECT 1" in namespace `my_db`
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SELECT 1;"
/// }
/// ```
///
/// This is the same as the example above, but has an explicit query language
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SELECT 1;"
/// "query_type": "sql"
/// }
/// ```
///
/// This runs the 'SHOW DATABASES' InfluxQL command (the `sql_query` field name is misleading)
///
/// ```json
/// {
/// "namespace_name": "my_db",
/// "sql_query": "SHOW DATABASES;"
/// "query_type": "influxql"
/// }
/// ```
fn decode_json(ticket: Bytes) -> Result<Self, String> { fn decode_json(ticket: Bytes) -> Result<Self, String> {
let json_str = String::from_utf8(ticket.to_vec()).map_err(|_| "Not UTF8".to_string())?; let json_str = String::from_utf8(ticket.to_vec()).map_err(|_| "Not UTF8".to_string())?;
@ -203,6 +216,7 @@ impl IoxGetRequest {
}) })
} }
/// See comments on [`IoxGetRequest`] for details of this format
fn decode_protobuf(ticket: Bytes) -> Result<Self, Error> { fn decode_protobuf(ticket: Bytes) -> Result<Self, Error> {
let read_info = proto::ReadInfo::decode(ticket).context(DecodeSnafu)?; let read_info = proto::ReadInfo::decode(ticket).context(DecodeSnafu)?;