1"""sqlglot expressions functions."""
  2
  3from __future__ import annotations
  4
  5import typing as t
  6
  7from sqlglot.expressions.core import (
  8    Expression,
  9    Func,
 10    Binary,
 11    SubqueryPredicate,
 12    ExpOrStr,
 13    maybe_parse,
 14    maybe_copy,
 15)
 16
 17# Re-export from focused submodules (backward compatibility)
 18from sqlglot.expressions.math import *  # noqa: F401,F403
 19from sqlglot.expressions.string import *  # noqa: F401,F403
 20from sqlglot.expressions.temporal import *  # noqa: F401,F403
 21from sqlglot.expressions.aggregate import *  # noqa: F401,F403
 22from sqlglot.expressions.array import *  # noqa: F401,F403
 23from sqlglot.expressions.json import *  # noqa: F401,F403
 24
 25if t.TYPE_CHECKING:
 26    from sqlglot.expressions.datatypes import DataType, DATA_TYPE
 27    from typing_extensions import Unpack
 28    from sqlglot._typing import ParserArgs
 29
 30
 31# Cast / type conversion
 32
 33
 34class Cast(Expression, Func):
 35    is_cast: t.ClassVar[bool] = True
 36    arg_types = {
 37        "this": True,
 38        "to": True,
 39        "format": False,
 40        "safe": False,
 41        "action": False,
 42        "default": False,
 43    }
 44
 45    @property
 46    def name(self) -> str:
 47        return self.this.name
 48
 49    @property
 50    def to(self) -> DataType:
 51        return self.args["to"]
 52
 53    @property
 54    def output_name(self) -> str:
 55        return self.name
 56
 57    def is_type(self, *dtypes: DATA_TYPE) -> bool:
 58        """
 59        Checks whether this Cast's DataType matches one of the provided data types. Nested types
 60        like arrays or structs will be compared using "structural equivalence" semantics, so e.g.
 61        array<int> != array<float>.
 62
 63        Args:
 64            dtypes: the data types to compare this Cast's DataType to.
 65
 66        Returns:
 67            True, if and only if there is a type in `dtypes` which is equal to this Cast's DataType.
 68        """
 69        return self.to.is_type(*dtypes)
 70
 71
 72class TryCast(Cast):
 73    arg_types = {**Cast.arg_types, "requires_string": False}
 74
 75
 76class JSONCast(Cast):
 77    pass
 78
 79
 80class CastToStrType(Expression, Func):
 81    arg_types = {"this": True, "to": True}
 82
 83
 84class Convert(Expression, Func):
 85    arg_types = {"this": True, "expression": True, "style": False, "safe": False}
 86
 87
 88# Conditional
 89
 90
 91class If(Expression, Func):
 92    arg_types = {"this": True, "true": True, "false": False}
 93    _sql_names = ["IF", "IIF"]
 94
 95
 96class Case(Expression, Func):
 97    arg_types = {"this": False, "ifs": True, "default": False}
 98
 99    def when(
100        self,
101        condition: ExpOrStr,
102        then: ExpOrStr,
103        copy: bool = True,
104        **opts: Unpack[ParserArgs],
105    ) -> Case:
106        instance = maybe_copy(self, copy)
107        instance.append(
108            "ifs",
109            If(
110                this=maybe_parse(condition, copy=copy, **opts),
111                true=maybe_parse(then, copy=copy, **opts),
112            ),
113        )
114        return instance
115
116    def else_(self, condition: ExpOrStr, copy: bool = True, **opts: Unpack[ParserArgs]) -> Case:
117        instance = maybe_copy(self, copy)
118        instance.set("default", maybe_parse(condition, copy=copy, **opts))
119        return instance
120
121
122class Coalesce(Expression, Func):
123    arg_types = {"this": True, "expressions": False, "is_nvl": False, "is_null": False}
124    is_var_len_args = True
125    _sql_names = ["COALESCE", "IFNULL", "NVL"]
126
127
128class DecodeCase(Expression, Func):
129    arg_types = {"expressions": True}
130    is_var_len_args = True
131
132
133class EqualNull(Expression, Func):
134    arg_types = {"this": True, "expression": True}
135
136
137class Greatest(Expression, Func):
138    arg_types = {"this": True, "expressions": False, "ignore_nulls": True}
139    is_var_len_args = True
140
141
142class Least(Expression, Func):
143    arg_types = {"this": True, "expressions": False, "ignore_nulls": True}
144    is_var_len_args = True
145
146
147class Nullif(Expression, Func):
148    arg_types = {"this": True, "expression": True}
149
150
151class ObjectTransform(Expression, Func):
152    arg_types = {"this": True, "keep": False, "set_": False}
153
154
155class Nvl2(Expression, Func):
156    arg_types = {"this": True, "true": True, "false": False}
157
158
159class Try(Expression, Func):
160    pass
161
162
163# Predicates / misc functions
164
165
166class Collate(Expression, Binary, Func):
167    pass
168
169
170class Collation(Expression, Func):
171    pass
172
173
174class ConnectByRoot(Expression, Func):
175    pass
176
177
178class CheckXml(Expression, Func):
179    arg_types = {"this": True, "disable_auto_convert": False}
180
181
182class Exists(Expression, Func, SubqueryPredicate):
183    arg_types = {"this": True, "expression": False}
184
185
186# Type coercions / lax types
187
188
189class Float64(Expression, Func):
190    arg_types = {"this": True, "expression": False}
191
192
193class Int64(Expression, Func):
194    pass
195
196
197class IsArray(Expression, Func):
198    pass
199
200
201class IsNullValue(Expression, Func):
202    pass
203
204
205class LaxBool(Expression, Func):
206    pass
207
208
209class LaxFloat64(Expression, Func):
210    pass
211
212
213class LaxInt64(Expression, Func):
214    pass
215
216
217class LaxString(Expression, Func):
218    pass
219
220
221class ToBoolean(Expression, Func):
222    arg_types = {"this": True, "safe": False}
223
224
225class ToVariant(Expression, Func):
226    pass
227
228
229# Session / context functions
230
231
232class CurrentAccount(Expression, Func):
233    arg_types = {}
234
235
236class CurrentAccountName(Expression, Func):
237    arg_types = {}
238
239
240class CurrentAvailableRoles(Expression, Func):
241    arg_types = {}
242
243
244class CurrentCatalog(Expression, Func):
245    arg_types = {}
246
247
248class CurrentClient(Expression, Func):
249    arg_types = {}
250
251
252class CurrentDatabase(Expression, Func):
253    arg_types = {}
254
255
256class CurrentIpAddress(Expression, Func):
257    arg_types = {}
258
259
260class CurrentOrganizationName(Expression, Func):
261    arg_types = {}
262
263
264class CurrentOrganizationUser(Expression, Func):
265    arg_types = {}
266
267
268class CurrentRegion(Expression, Func):
269    arg_types = {}
270
271
272class CurrentRole(Expression, Func):
273    arg_types = {}
274
275
276class CurrentRoleType(Expression, Func):
277    arg_types = {}
278
279
280class CurrentSchema(Expression, Func):
281    arg_types = {"this": False}
282
283
284class CurrentSchemas(Expression, Func):
285    arg_types = {"this": False}
286
287
288class CurrentSecondaryRoles(Expression, Func):
289    arg_types = {}
290
291
292class CurrentSession(Expression, Func):
293    arg_types = {}
294
295
296class CurrentStatement(Expression, Func):
297    arg_types = {}
298
299
300class CurrentTransaction(Expression, Func):
301    arg_types = {}
302
303
304class CurrentUser(Expression, Func):
305    arg_types = {"this": False}
306
307
308class CurrentUserId(Expression, Func):
309    arg_types = {}
310
311
312class CurrentVersion(Expression, Func):
313    arg_types = {}
314
315
316class CurrentWarehouse(Expression, Func):
317    arg_types = {}
318
319
320class SessionUser(Expression, Func):
321    arg_types = {}
322
323
324# ML / AI
325
326
327class AIClassify(Expression, Func):
328    arg_types = {"this": True, "categories": True, "config": False}
329    _sql_names = ["AI_CLASSIFY"]
330
331
332class AIEmbed(Expression, Func):
333    arg_types = {"expressions": True}
334    is_var_len_args = True
335    _sql_names = ["AI_EMBED"]
336
337
338class AISimilarity(Expression, Func):
339    arg_types = {"expressions": True}
340    is_var_len_args = True
341    _sql_names = ["AI_SIMILARITY"]
342
343
344class AIGenerate(Expression, Func):
345    arg_types = {"expressions": True}
346    is_var_len_args = True
347    _sql_names = ["AI_GENERATE"]
348
349
350class FeaturesAtTime(Expression, Func):
351    arg_types = {"this": True, "time": False, "num_rows": False, "ignore_feature_nulls": False}
352
353
354class GenerateEmbedding(Expression, Func):
355    arg_types = {"this": True, "expression": True, "params_struct": False, "is_text": False}
356
357
358class GenerateText(Expression, Func):
359    arg_types = {"this": True, "expression": False, "params_struct": False}
360
361
362class GenerateTable(Expression, Func):
363    arg_types = {"this": True, "expression": False, "params_struct": False}
364
365
366class GenerateBool(Expression, Func):
367    arg_types = {"this": True, "expression": False, "params_struct": False}
368
369
370class GenerateInt(Expression, Func):
371    arg_types = {"this": True, "expression": False, "params_struct": False}
372
373
374class GenerateDouble(Expression, Func):
375    arg_types = {"this": True, "expression": False, "params_struct": False}
376
377
378class MLForecast(Expression, Func):
379    arg_types = {"this": True, "expression": False, "params_struct": False}
380
381
382class AIForecast(Expression, Func):
383    arg_types = {
384        "this": True,
385        "data_col": False,
386        "timestamp_col": False,
387        "model": False,
388        "id_cols": False,
389        "horizon": False,
390        "forecast_end_timestamp": False,
391        "confidence_level": False,
392        "output_historical_time_series": False,
393        "context_window": False,
394    }
395
396
397class MLTranslate(Expression, Func):
398    arg_types = {"this": True, "expression": True, "params_struct": True}
399
400
401class Predict(Expression, Func):
402    arg_types = {"this": True, "expression": True, "params_struct": False}
403
404
405class VectorSearch(Expression, Func):
406    arg_types = {
407        "this": True,
408        "column_to_search": True,
409        "query_table": True,
410        "query_column_to_search": False,
411        "top_k": False,
412        "distance_type": False,
413        "options": False,
414    }
415
416
417# Data reading
418
419
420class ReadCSV(Expression, Func):
421    _sql_names = ["READ_CSV"]
422    is_var_len_args = True
423    arg_types = {"this": True, "expressions": False}
424
425
426class ReadParquet(Expression, Func):
427    is_var_len_args = True
428    arg_types = {"expressions": True}
429
430
431# XML
432
433
434class XMLElement(Expression, Func):
435    _sql_names = ["XMLELEMENT"]
436    arg_types = {"this": True, "expressions": False, "evalname": False}
437
438
439class XMLGet(Expression, Func):
440    _sql_names = ["XMLGET"]
441    arg_types = {"this": True, "expression": True, "instance": False}
442
443
444class XMLTable(Expression, Func):
445    arg_types = {
446        "this": True,
447        "namespaces": False,
448        "passing": False,
449        "columns": False,
450        "by_ref": False,
451    }
452
453
454# Network / domain
455
456
457class Host(Expression, Func):
458    pass
459
460
461class NetFunc(Expression, Func):
462    pass
463
464
465class ParseIp(Expression, Func):
466    arg_types = {"this": True, "type": True, "permissive": False}
467
468
469class RegDomain(Expression, Func):
470    pass
471
472
473# Misc utility
474
475
476class Columns(Expression, Func):
477    arg_types = {"this": True, "unpack": False}
478
479
480class Normal(Expression, Func):
481    arg_types = {"this": True, "stddev": True, "gen": True}
482
483
484class Rand(Expression, Func):
485    _sql_names = ["RAND", "RANDOM"]
486    arg_types = {"this": False, "lower": False, "upper": False}
487
488
489class Randn(Expression, Func):
490    arg_types = {"this": False}
491
492
493class Randstr(Expression, Func):
494    arg_types = {"this": True, "generator": False}
495
496
497class RangeBucket(Expression, Func):
498    arg_types = {"this": True, "expression": True}
499
500
501class RangeN(Expression, Func):
502    arg_types = {"this": True, "expressions": True, "each": False}
503
504
505class Seq1(Expression, Func):
506    arg_types = {"this": False}
507
508
509class Seq2(Expression, Func):
510    arg_types = {"this": False}
511
512
513class Seq4(Expression, Func):
514    arg_types = {"this": False}
515
516
517class Seq8(Expression, Func):
518    arg_types = {"this": False}
519
520
521class Uniform(Expression, Func):
522    arg_types = {"this": True, "expression": True, "gen": False, "seed": False}
523
524
525class Uuid(Expression, Func):
526    _sql_names = ["UUID", "GEN_RANDOM_UUID", "GENERATE_UUID", "UUID_STRING"]
527
528    arg_types = {"this": False, "name": False, "is_string": False}
529
530
531class WeekStart(Expression, Func):
532    pass
533
534
535class WidthBucket(Expression, Func):
536    arg_types = {
537        "this": True,
538        "min_value": False,
539        "max_value": False,
540        "num_buckets": False,
541        "threshold": False,
542    }
543
544
545class Zipf(Expression, Func):
546    arg_types = {"this": True, "elementcount": True, "gen": True}