Class: ClickHouse::SQL::SelectQuery

Inherits:
Object
  • Object
show all
Includes:
Part
Defined in:
lib/clickhouse/sql/select_query.rb

Instance Method Summary collapse

Constructor Details

#initialize ⇒ ClickHouse::SQL::SelectQuery

Builds an empty mutable SELECT query.



11
12
13
14
15
16
17
18
19
20
21
 
# File 'lib/clickhouse/sql/select_query.rb', line 11

def initialize
  @selects = []
  @distinct = false
  @with = []
  @joins = []
  @wheres = []
  @havings = []
  @group_bys = []
  @order_bys = []
  @settings = []
end

Instance Method Details

#distinct ⇒ ClickHouse::SQL::SelectQuery

Renders SELECT DISTINCT instead of SELECT.

Returns:



26
27
28
29
 
# File 'lib/clickhouse/sql/select_query.rb', line 26

def distinct
  @distinct = true
  self
end

#from(table, as: nil, final: false) ⇒ ClickHouse::SQL::SelectQuery

Sets the FROM table expression.

A ClickHouse::SQL::Table handle owns its alias so column references built from the handle always match the rendered clause; passing as: alongside a handle raises.

Parameters:

  • table (String, Symbol, ClickHouse::SQL::Part) —

    Trusted table expression.

  • as (String, Symbol, nil) (defaults to: nil) —

    Optional table alias; only valid for string/symbol table names — a ClickHouse::SQL::Table handle owns its alias.

  • final (Boolean) (defaults to: false) —

    Whether to append ClickHouse FINAL.

Returns:



88
89
90
91
92
93
 
# File 'lib/clickhouse/sql/select_query.rb', line 88

def from(table, as: nil, final: false)
  @from = ClickHouse::SQL.coerce_raw_expression(table)
  @from_alias = ClickHouse::SQL.resolve_table_alias(table, as)
  @from_final = final
  self
end

#from_subquery(query, as:) ⇒ ClickHouse::SQL::SelectQuery

Sets the FROM clause to a nested query.

Parameters:

  • query (String, Symbol, ClickHouse::SQL::Part) —

    Subquery expression.

  • as (String, Symbol, ClickHouse::SQL::Table) —

    Required table alias. A table handle contributes its qualifier so references built from the handle match the rendered alias.

Returns:



102
103
104
105
106
107
 
# File 'lib/clickhouse/sql/select_query.rb', line 102

def from_subquery(query, as:)
  @from = ClickHouse::SQL.fragment("({query})", query: ClickHouse::SQL.coerce_expression(query))
  @from_alias = as.is_a?(ClickHouse::SQL::Table) ? as.qualifier : as
  @from_final = false
  self
end

#group_by(*expressions) ⇒ ClickHouse::SQL::SelectQuery

Appends GROUP BY expressions.

Parameters:

Returns:



185
186
187
 
# File 'lib/clickhouse/sql/select_query.rb', line 185

def group_by(*expressions)
  append_raw_expressions(@group_bys, expressions)
end

#having(condition = nil, *fills, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Appends a HAVING condition, or an array of HAVING conditions, later rendered with AND.

Parameters:

  • condition (String, Symbol, ClickHouse::SQL::Part, Array, nil) (defaults to: nil) —

    HAVING condition(s).

  • fills (Array<ClickHouse::SQL::Part>) —

    Positional fills for anonymous {} slots.

  • bindings (Hash) —

    Placeholder bindings for the condition.

Returns:



177
178
179
 
# File 'lib/clickhouse/sql/select_query.rb', line 177

def having(condition = nil, *fills, **bindings)
  append_clause(@havings, condition, fills, bindings)
end

#inner_join(table, as: nil, final: false, on:) ⇒ ClickHouse::SQL::SelectQuery

Appends an INNER JOIN clause.

Parameters:

  • table (String, Symbol, ClickHouse::SQL::Part) —

    Trusted table expression.

  • as (String, Symbol, nil) (defaults to: nil) —

    Optional table alias; only valid for string/symbol table names — a ClickHouse::SQL::Table handle owns its alias.

  • final (Boolean) (defaults to: false) —

    Whether to append ClickHouse FINAL.

  • on (String, ClickHouse::SQL::Part, Array) —

    ON conditions.

Returns:



143
144
145
 
# File 'lib/clickhouse/sql/select_query.rb', line 143

def inner_join(table, as: nil, final: false, on:)
  join(table, type: "INNER", as:, final:, on:)
end

#join(table, type: "INNER", as: nil, final: false, on:) ⇒ ClickHouse::SQL::SelectQuery

Appends a JOIN clause.

Parameters:

  • table (String, Symbol, ClickHouse::SQL::Part) —

    Trusted table expression.

  • type (String) (defaults to: "INNER") —

    JOIN type, for example INNER or LEFT.

  • as (String, Symbol, nil) (defaults to: nil) —

    Optional table alias; only valid for string/symbol table names — a ClickHouse::SQL::Table handle owns its alias.

  • final (Boolean) (defaults to: false) —

    Whether to append ClickHouse FINAL.

  • on (String, ClickHouse::SQL::Part, Array) —

    ON conditions.

Returns:



118
119
120
121
 
# File 'lib/clickhouse/sql/select_query.rb', line 118

def join(table, type: "INNER", as: nil, final: false, on:)
  @joins << Join.new(table, type:, as:, final:, on:)
  self
end

#joins(*joins) ⇒ ClickHouse::SQL::SelectQuery

Appends pre-rendered JOIN fragments.

Parameters:

Returns:



151
152
153
154
155
156
157
 
# File 'lib/clickhouse/sql/select_query.rb', line 151

def joins(*joins)
  joins.flatten.compact.each do |join|
    @joins << ClickHouse::SQL.coerce_expression(join)
  end

  self
end

#left_join(table, as: nil, final: false, on:) ⇒ ClickHouse::SQL::SelectQuery

Appends a LEFT JOIN clause.

Parameters:

  • table (String, Symbol, ClickHouse::SQL::Part) —

    Trusted table expression.

  • as (String, Symbol, nil) (defaults to: nil) —

    Optional table alias; only valid for string/symbol table names — a ClickHouse::SQL::Table handle owns its alias.

  • final (Boolean) (defaults to: false) —

    Whether to append ClickHouse FINAL.

  • on (String, ClickHouse::SQL::Part, Array) —

    ON conditions.

Returns:



131
132
133
 
# File 'lib/clickhouse/sql/select_query.rb', line 131

def left_join(table, as: nil, final: false, on:)
  join(table, type: "LEFT", as:, final:, on:)
end

#limit(expression = nil, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Sets the LIMIT expression.

Parameters:

  • expression (String, Symbol, ClickHouse::SQL::Part, nil) (defaults to: nil) —

    LIMIT expression.

  • bindings (Hash) —

    Placeholder bindings for the LIMIT expression.

Returns:



202
203
204
205
 
# File 'lib/clickhouse/sql/select_query.rb', line 202

def limit(expression = nil, **bindings)
  @limit = one_fragment(expression, bindings)
  self
end

#offset(expression = nil, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Sets the OFFSET expression.

Parameters:

  • expression (String, Symbol, ClickHouse::SQL::Part, nil) (defaults to: nil) —

    OFFSET expression.

  • bindings (Hash) —

    Placeholder bindings for the OFFSET expression.

Returns:



212
213
214
215
 
# File 'lib/clickhouse/sql/select_query.rb', line 212

def offset(expression = nil, **bindings)
  @offset = one_fragment(expression, bindings)
  self
end

#order_by(*expressions) ⇒ ClickHouse::SQL::SelectQuery

Appends ORDER BY expressions.

Parameters:

Returns:



193
194
195
 
# File 'lib/clickhouse/sql/select_query.rb', line 193

def order_by(*expressions)
  append_raw_expressions(@order_bys, expressions)
end

#placeholder_types ⇒ Hash{Symbol=>String}

Returns ClickHouse placeholder types used by the SELECT query.

Returns:

  • (Hash{Symbol=>String}) —

    Placeholder types keyed by name.



267
268
269
 
# File 'lib/clickhouse/sql/select_query.rb', line 267

def placeholder_types
  ClickHouse::SQL.collect_placeholder_types(query_parts)
end

#placeholders ⇒ Hash{Symbol=>Object}

Returns typed placeholder values used by the SELECT query.

Returns:

  • (Hash{Symbol=>Object}) —

    Placeholder values keyed by name.



260
261
262
 
# File 'lib/clickhouse/sql/select_query.rb', line 260

def placeholders
  ClickHouse::SQL.collect_placeholders(query_parts)
end

#select(*columns, **aliases) ⇒ ClickHouse::SQL::SelectQuery

Appends SELECT expressions.

Parameters:

Returns:



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/clickhouse/sql/select_query.rb', line 36

def select(*columns, **aliases)
  columns.flatten.compact.each do |column|
    @selects << SelectItem.new(expression: ClickHouse::SQL.coerce_raw_expression(column))
  end

  aliases.each do |alias_name, expression|
    @selects << SelectItem.new(expression: ClickHouse::SQL.coerce_raw_expression(expression), alias_name:)
  end

  self
end

#setting(name, value) ⇒ ClickHouse::SQL::SelectQuery

Appends one validated SETTINGS assignment.

Parameters:

  • name (String, Symbol) —

    ClickHouse setting name.

  • value (String, Integer, Float, Boolean) —

    Inline setting value.

Returns:



237
238
239
240
 
# File 'lib/clickhouse/sql/select_query.rb', line 237

def setting(name, value)
  @settings << Setting.new(name, value)
  self
end

#settings(*settings, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Appends static SETTINGS fragments.

Parameters:

  • settings (Array<String, Symbol, ClickHouse::SQL::Part, nil>) —

    SETTINGS fragments.

  • bindings (Hash) —

    Unsupported; ClickHouse does not parameterize SETTINGS.

Returns:



222
223
224
225
226
227
228
229
230
 
# File 'lib/clickhouse/sql/select_query.rb', line 222

def settings(*settings, **bindings)
  if bindings.any?
    raise Error, "ClickHouse SETTINGS do not support query parameters; use setting(name, value) for dynamic setting values"
  end

  settings.flatten.compact.each { |setting| @settings << ClickHouse::SQL.coerce_expression(setting) }
  validate_settings!
  self
end

#to_query ⇒ ClickHouse::SQL::Query

Converts this builder into an immutable query object accepted by ClickHouse::HTTPClient.

Returns:



274
275
276
277
278
279
280
281
 
# File 'lib/clickhouse/sql/select_query.rb', line 274

def to_query
  Query.new(
    sql: to_sql,
    redacted_sql: to_redacted_sql(Query.redacted_bind_index_manager),
    placeholders:,
    placeholder_types:
  )
end

#to_redacted_sql(bind_index_manager = ClickHouse::SQL::BindIndexManager.new) ⇒ String

Renders the SELECT query with typed placeholders replaced by bind markers.

Parameters:

Returns:

  • (String) —

    Redacted SQL query text.



253
254
255
 
# File 'lib/clickhouse/sql/select_query.rb', line 253

def to_redacted_sql(bind_index_manager = ClickHouse::SQL::BindIndexManager.new)
  render(redacted: true, bind_index_manager:)
end

#to_sql ⇒ String

Renders the SELECT query with ClickHouse typed placeholders intact.

Returns:

  • (String) —

    SQL query text.



245
246
247
 
# File 'lib/clickhouse/sql/select_query.rb', line 245

def to_sql
  render(redacted: false)
end

#where(condition = nil, *fills, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Appends a WHERE condition, or an array of WHERE conditions, later rendered with AND.

Parameters:

  • condition (String, Symbol, ClickHouse::SQL::Part, Array, nil) (defaults to: nil) —

    WHERE condition(s).

  • fills (Array<ClickHouse::SQL::Part>) —

    Positional fills for anonymous {} slots.

  • bindings (Hash) —

    Placeholder bindings for the condition.

Returns:



166
167
168
 
# File 'lib/clickhouse/sql/select_query.rb', line 166

def where(condition = nil, *fills, **bindings)
  append_clause(@wheres, condition, fills, bindings)
end

#with(fragment = nil, *fills, **bindings) ⇒ ClickHouse::SQL::SelectQuery

Appends a WITH/CTE fragment, or an array of WITH/CTE fragments.

Parameters:

  • fragment (String, Symbol, ClickHouse::SQL::Part, Array, nil) (defaults to: nil) —

    WITH fragment(s).

  • fills (Array<ClickHouse::SQL::Part>) —

    Positional fills for anonymous {} slots.

  • bindings (Hash) —

    Placeholder bindings for the fragment.

Returns:



54
55
56
 
# File 'lib/clickhouse/sql/select_query.rb', line 54

def with(fragment = nil, *fills, **bindings)
  append_clause(@with, fragment, fills, bindings)
end

#with_cte(handle, query) ⇒ ClickHouse::SQL::SelectQuery

Appends a CTE named by a table handle.

Parameters:

Returns:



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/clickhouse/sql/select_query.rb', line 63

def with_cte(handle, query)
  unless handle.is_a?(ClickHouse::SQL::Table)
    raise Error, "CTE handle must be a table handle, got #{handle.class}"
  end

  name = ClickHouse::SQL.validate_alias!(handle.name)
  @with << ClickHouse::SQL.fragment(
    "{} AS ({})",
    ClickHouse::SQL.raw_static(name),
    ClickHouse::SQL.coerce_expression(query)
  )
  self
end