Class: Rafflesia::Query

Inherits:
Object
  • Object
show all
Defined in:
lib/rafflesia/query.rb

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Query

Returns a new instance of Query.



9
10
11
 
# File 'lib/rafflesia/query.rb', line 9

def initialize(client)
  @client = client
end

Instance Method Details

#explain(sources:, sql:, allow_unverified_joins: nil, budget: nil, budget_profile: nil, cursor: nil, dialect: nil, join_evidence_policy: nil, limit: nil, ontology_digest: nil, required_join_evidence: nil, strict_joins: nil, request_options: {}) ⇒ Rafflesia::EnvelopeQueryExplainData

POST /v1/query/explain

Parameters:

  • allow_unverified_joins (Boolean, nil) (defaults to: nil) —

    Explicit escape hatch for cross-database joins. When false, every cross-database join is strict and requires retained cardinality-consistent evidence.

  • budget (Rafflesia::QueryBudget, nil) (defaults to: nil) —

    Optional explicit overrides bounded by the selected profile's published maximums.

  • budget_profile (Rafflesia::Types::QueryRequestBudgetProfile, nil) (defaults to: nil) —

    Calibrated execution profile; defaults to interactive.

  • cursor (String, nil) (defaults to: nil)
  • dialect (String, nil) (defaults to: nil) —

    Pinned portable SQL contract; omitted selects the current contract.

  • join_evidence_policy (Rafflesia::Types::QueryRequestJoinEvidencePolicy, nil) (defaults to: nil) —

    Automatically resolve and bind retained measurements for every complete declared SQL join. Cross-database joins default to cardinality_consistent unless allow_unverified_joins is true.

  • limit (Integer, nil) (defaults to: nil)
  • ontology_digest (String, nil) (defaults to: nil) —

    Optional exact ontology snapshot precondition. The request fails if this build cannot serve that digest.

  • required_join_evidence (Array<Rafflesia::DatabaseJoinEvidenceRequirement>, nil) (defaults to: nil) —

    Optional exact retained join-measurement preconditions. Each row is verified against the named pinned sources before planning or execution.

  • sources (Array<Rafflesia::QuerySource>, nil)
  • sql (String)
  • strict_joins (Boolean, nil) (defaults to: nil) —

    When true, coordinate-unsafe joins (unregistered pairs, missing keys, lossy or coordinate-range mappings, cross-release joins) fail the query instead of returning advisory warnings.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/rafflesia/query.rb', line 84

def explain(
  sources:,
  sql:,
  allow_unverified_joins: nil,
  budget: nil,
  budget_profile: nil,
  cursor: nil,
  dialect: nil,
  join_evidence_policy: nil,
  limit: nil,
  ontology_digest: nil,
  required_join_evidence: nil,
  strict_joins: nil,
  request_options: {}
)
  body = {
    'allow_unverified_joins' => allow_unverified_joins,
    'budget' => budget,
    'budget_profile' => budget_profile,
    'cursor' => cursor,
    'dialect' => dialect,
    'join_evidence_policy' => join_evidence_policy,
    'limit' => limit,
    'ontology_digest' => ontology_digest,
    'required_join_evidence' => required_join_evidence,
    'sources' => sources,
    'sql' => sql,
    'strict_joins' => strict_joins
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/query/explain',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeQueryExplainData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#run(sources:, sql:, allow_unverified_joins: nil, budget: nil, budget_profile: nil, cursor: nil, dialect: nil, join_evidence_policy: nil, limit: nil, ontology_digest: nil, required_join_evidence: nil, strict_joins: nil, request_options: {}) ⇒ Rafflesia::EnvelopeQueryData

POST /v1/query

Parameters:

  • allow_unverified_joins (Boolean, nil) (defaults to: nil) —

    Explicit escape hatch for cross-database joins. When false, every cross-database join is strict and requires retained cardinality-consistent evidence.

  • budget (Rafflesia::QueryBudget, nil) (defaults to: nil) —

    Optional explicit overrides bounded by the selected profile's published maximums.

  • budget_profile (Rafflesia::Types::QueryRequestBudgetProfile, nil) (defaults to: nil) —

    Calibrated execution profile; defaults to interactive.

  • cursor (String, nil) (defaults to: nil)
  • dialect (String, nil) (defaults to: nil) —

    Pinned portable SQL contract; omitted selects the current contract.

  • join_evidence_policy (Rafflesia::Types::QueryRequestJoinEvidencePolicy, nil) (defaults to: nil) —

    Automatically resolve and bind retained measurements for every complete declared SQL join. Cross-database joins default to cardinality_consistent unless allow_unverified_joins is true.

  • limit (Integer, nil) (defaults to: nil)
  • ontology_digest (String, nil) (defaults to: nil) —

    Optional exact ontology snapshot precondition. The request fails if this build cannot serve that digest.

  • required_join_evidence (Array<Rafflesia::DatabaseJoinEvidenceRequirement>, nil) (defaults to: nil) —

    Optional exact retained join-measurement preconditions. Each row is verified against the named pinned sources before planning or execution.

  • sources (Array<Rafflesia::QuerySource>, nil)
  • sql (String)
  • strict_joins (Boolean, nil) (defaults to: nil) —

    When true, coordinate-unsafe joins (unregistered pairs, missing keys, lossy or coordinate-range mappings, cross-release joins) fail the query instead of returning advisory warnings.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



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
 
# File 'lib/rafflesia/query.rb', line 28

def run(
  sources:,
  sql:,
  allow_unverified_joins: nil,
  budget: nil,
  budget_profile: nil,
  cursor: nil,
  dialect: nil,
  join_evidence_policy: nil,
  limit: nil,
  ontology_digest: nil,
  required_join_evidence: nil,
  strict_joins: nil,
  request_options: {}
)
  body = {
    'allow_unverified_joins' => allow_unverified_joins,
    'budget' => budget,
    'budget_profile' => budget_profile,
    'cursor' => cursor,
    'dialect' => dialect,
    'join_evidence_policy' => join_evidence_policy,
    'limit' => limit,
    'ontology_digest' => ontology_digest,
    'required_join_evidence' => required_join_evidence,
    'sources' => sources,
    'sql' => sql,
    'strict_joins' => strict_joins
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/query',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeQueryData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end