1"""sqlglot expressions - string, encoding, hashing, and regex functions."""
  2
  3from __future__ import annotations
  4
  5from sqlglot.expressions.core import Expression, Func, Binary, Predicate
  6
  7
  8# String basics
  9
 10
 11class Ascii(Expression, Func):
 12    pass
 13
 14
 15class BitLength(Expression, Func):
 16    pass
 17
 18
 19class ByteLength(Expression, Func):
 20    pass
 21
 22
 23class Chr(Expression, Func):
 24    arg_types = {"expressions": True, "charset": False}
 25    is_var_len_args = True
 26    _sql_names = ["CHR", "CHAR"]
 27
 28
 29class Concat(Expression, Func):
 30    arg_types = {"expressions": True, "safe": False, "coalesce": False}
 31    is_var_len_args = True
 32
 33
 34class ConcatWs(Concat):
 35    arg_types = {**Concat.arg_types, "flatten": False}
 36    _sql_names = ["CONCAT_WS"]
 37
 38
 39class Contains(Expression, Func):
 40    arg_types = {"this": True, "expression": True, "json_scope": False}
 41
 42
 43class Elt(Expression, Func):
 44    arg_types = {"this": True, "expressions": True}
 45    is_var_len_args = True
 46
 47
 48class EndsWith(Expression, Func):
 49    _sql_names = ["ENDS_WITH", "ENDSWITH"]
 50    arg_types = {"this": True, "expression": True}
 51
 52
 53class Format(Expression, Func):
 54    arg_types = {"this": True, "expressions": False}
 55    is_var_len_args = True
 56
 57
 58class Initcap(Expression, Func):
 59    arg_types = {"this": True, "expression": False}
 60
 61
 62class IsAscii(Expression, Func):
 63    pass
 64
 65
 66class Left(Expression, Func):
 67    arg_types = {"this": True, "expression": True, "negative_length_returns_empty": False}
 68
 69
 70class Length(Expression, Func):
 71    arg_types = {"this": True, "binary": False, "encoding": False}
 72    _sql_names = ["LENGTH", "LEN", "CHAR_LENGTH", "CHARACTER_LENGTH"]
 73
 74
 75class Levenshtein(Expression, Func):
 76    arg_types = {
 77        "this": True,
 78        "expression": False,
 79        "ins_cost": False,
 80        "del_cost": False,
 81        "sub_cost": False,
 82        "max_dist": False,
 83    }
 84
 85
 86class Lower(Expression, Func):
 87    _sql_names = ["LOWER", "LCASE"]
 88
 89
 90class MatchAgainst(Expression, Func):
 91    arg_types = {"this": True, "expressions": True, "modifier": False}
 92
 93
 94class Normalize(Expression, Func):
 95    arg_types = {"this": True, "form": False, "is_casefold": False}
 96
 97
 98class NumberToStr(Expression, Func):
 99    arg_types = {"this": True, "format": True, "culture": False}
100
101
102class Overlay(Expression, Func):
103    arg_types = {"this": True, "expression": True, "from_": True, "for_": False}
104
105
106class Pad(Expression, Func):
107    arg_types = {"this": True, "expression": True, "fill_pattern": False, "is_left": True}
108
109
110class Repeat(Expression, Func):
111    arg_types = {"this": True, "times": True}
112
113
114class Replace(Expression, Func):
115    arg_types = {"this": True, "expression": True, "replacement": False}
116
117
118class Reverse(Expression, Func):
119    pass
120
121
122class Right(Expression, Func):
123    arg_types = {"this": True, "expression": True, "negative_length_returns_empty": False}
124
125
126class RtrimmedLength(Expression, Func):
127    pass
128
129
130class Search(Expression, Func):
131    arg_types = {
132        "this": True,  # data_to_search / search_data
133        "expression": True,  # search_query / search_string
134        "json_scope": False,  # BigQuery: JSON_VALUES | JSON_KEYS | JSON_KEYS_AND_VALUES
135        "analyzer": False,  # Both: analyzer / ANALYZER
136        "analyzer_options": False,  # BigQuery: analyzer_options_values
137        "search_mode": False,  # Snowflake: OR | AND
138    }
139
140
141class SearchIp(Expression, Func):
142    arg_types = {"this": True, "expression": True}
143
144
145class Secret(Expression, Func):
146    arg_types = {"this": True, "expression": True}
147
148
149class Soundex(Expression, Func):
150    pass
151
152
153class SoundexP123(Expression, Func):
154    pass
155
156
157class Space(Expression, Func):
158    """
159    SPACE(n) → string consisting of n blank characters
160    """
161
162    pass
163
164
165class Split(Expression, Func):
166    arg_types = {
167        "this": True,
168        "expression": True,
169        "limit": False,
170        "null_returns_null": False,
171        "empty_delimiter_returns_whole": False,
172    }
173
174
175class SplitPart(Expression, Func):
176    arg_types = {
177        "this": True,
178        "delimiter": False,
179        "part_index": False,
180        "part_index_zero_as_one": False,  # usually part_index is 1-based, however Snowflake allows 0 and treats it as 1
181        "empty_delimiter_returns_whole": False,  # whether the whole input string should be returned if the delimiter string is empty (i.e. Snowflake)
182    }
183
184
185class Strtok(Expression, Func):
186    arg_types = {
187        "this": True,
188        "delimiter": False,
189        "part_index": False,
190    }
191
192
193class StartsWith(Expression, Func):
194    _sql_names = ["STARTS_WITH", "STARTSWITH"]
195    arg_types = {"this": True, "expression": True}
196
197
198class StrPosition(Expression, Func):
199    arg_types = {
200        "this": True,
201        "substr": True,
202        "position": False,
203        "occurrence": False,
204        "clamp_position": False,
205    }
206
207
208class StrToMap(Expression, Func):
209    arg_types = {
210        "this": True,
211        "pair_delim": False,
212        "key_value_delim": False,
213        "duplicate_resolution_callback": False,
214    }
215
216
217class String(Expression, Func):
218    arg_types = {"this": True, "zone": False}
219
220
221class Stuff(Expression, Func):
222    _sql_names = ["STUFF", "INSERT"]
223    arg_types = {"this": True, "start": True, "length": True, "expression": True}
224
225
226class Substring(Expression, Func):
227    _sql_names = ["SUBSTRING", "SUBSTR"]
228    arg_types = {"this": True, "start": False, "length": False, "zero_start": False}
229
230
231class SubstringIndex(Expression, Func):
232    """
233    SUBSTRING_INDEX(str, delim, count)
234
235    *count* > 0  → left slice before the *count*-th delimiter
236    *count* < 0  → right slice after the |count|-th delimiter
237    """
238
239    arg_types = {"this": True, "delimiter": True, "count": True}
240
241
242class Translate(Expression, Func):
243    arg_types = {"this": True, "from_": True, "to": True}
244
245
246class Trim(Expression, Func):
247    arg_types = {
248        "this": True,
249        "expression": False,
250        "position": False,
251        "collation": False,
252    }
253
254
255class Unicode(Expression, Func):
256    arg_types = {"this": True, "empty_is_zero": False}
257
258
259class Upper(Expression, Func):
260    _sql_names = ["UPPER", "UCASE"]
261
262
263class WeightString(Expression, Func):
264    arg_types = {"this": True, "to": False}
265
266
267# Encoding / base conversion
268
269
270class Base64DecodeBinary(Expression, Func):
271    arg_types = {"this": True, "alphabet": False}
272
273
274class Base64DecodeString(Expression, Func):
275    arg_types = {"this": True, "alphabet": False}
276
277
278class Base64Encode(Expression, Func):
279    arg_types = {"this": True, "max_line_length": False, "alphabet": False}
280
281
282class CodePointsToBytes(Expression, Func):
283    pass
284
285
286class CodePointsToString(Expression, Func):
287    pass
288
289
290class ConvertToCharset(Expression, Func):
291    arg_types = {"this": True, "dest": True, "source": False}
292
293
294class Decode(Expression, Func):
295    arg_types = {"this": True, "charset": True, "replace": False}
296
297
298class Encode(Expression, Func):
299    arg_types = {"this": True, "charset": True}
300
301
302class FromBase(Expression, Func):
303    arg_types = {"this": True, "expression": True}
304
305
306class FromBase32(Expression, Func):
307    pass
308
309
310class FromBase64(Expression, Func):
311    pass
312
313
314class Hex(Expression, Func):
315    arg_types = {"this": True, "case": False}
316
317
318class HexDecodeString(Expression, Func):
319    pass
320
321
322class LowerHex(Hex):
323    pass
324
325
326class SafeConvertBytesToString(Expression, Func):
327    pass
328
329
330class ToBase32(Expression, Func):
331    pass
332
333
334class ToBase64(Expression, Func):
335    pass
336
337
338class ToBinary(Expression, Func):
339    arg_types = {"this": True, "format": False, "safe": False}
340
341
342class ToChar(Expression, Func):
343    arg_types = {
344        "this": True,
345        "format": False,
346        "nlsparam": False,
347        "is_numeric": False,
348    }
349
350
351class ToCodePoints(Expression, Func):
352    pass
353
354
355class ToDecfloat(Expression, Func):
356    arg_types = {
357        "this": True,
358        "format": False,
359    }
360
361
362class ToDouble(Expression, Func):
363    arg_types = {
364        "this": True,
365        "format": False,
366        "safe": False,
367    }
368
369
370class ToFile(Expression, Func):
371    arg_types = {
372        "this": True,
373        "path": False,
374        "safe": False,
375    }
376
377
378class ToNumber(Expression, Func):
379    arg_types = {
380        "this": True,
381        "format": False,
382        "nlsparam": False,
383        "precision": False,
384        "scale": False,
385        "safe": False,
386        "safe_name": False,
387        "default": False,
388    }
389
390
391class TryBase64DecodeBinary(Expression, Func):
392    arg_types = {"this": True, "alphabet": False}
393
394
395class TryBase64DecodeString(Expression, Func):
396    arg_types = {"this": True, "alphabet": False}
397
398
399class TryHexDecodeBinary(Expression, Func):
400    pass
401
402
403class TryHexDecodeString(Expression, Func):
404    pass
405
406
407class TryToDecfloat(Expression, Func):
408    arg_types = {
409        "this": True,
410        "format": False,
411    }
412
413
414class Unhex(Expression, Func):
415    arg_types = {"this": True, "expression": False}
416
417
418# Regex
419
420
421class RegexpCount(Expression, Func):
422    arg_types = {
423        "this": True,
424        "expression": True,
425        "position": False,
426        "parameters": False,
427    }
428
429
430class RegexpExtract(Expression, Func):
431    arg_types = {
432        "this": True,
433        "expression": True,
434        "position": False,
435        "occurrence": False,
436        "parameters": False,
437        "group": False,
438        "null_if_pos_overflow": False,
439        "null_if_no_match": False,
440        "empty_if_group_missing": False,
441    }
442
443
444class RegexpExtractAll(Expression, Func):
445    arg_types = {
446        "this": True,
447        "expression": True,
448        "group": False,
449        "parameters": False,
450        "position": False,
451        "occurrence": False,
452    }
453
454
455class RegexpFullMatch(Expression, Binary, Predicate, Func):
456    arg_types = {"this": True, "expression": True, "options": False}
457
458
459class RegexpILike(Expression, Binary, Predicate, Func):
460    arg_types = {"this": True, "expression": True, "flag": False}
461
462
463class RegexpInstr(Expression, Func):
464    arg_types = {
465        "this": True,
466        "expression": True,
467        "position": False,
468        "occurrence": False,
469        "option": False,
470        "parameters": False,
471        "group": False,
472    }
473
474
475class RegexpReplace(Expression, Func):
476    arg_types = {
477        "this": True,
478        "expression": True,
479        "replacement": False,
480        "position": False,
481        "occurrence": False,
482        "modifiers": False,
483        "single_replace": False,
484    }
485
486
487class RegexpSplit(Expression, Func):
488    # "mode" is Dremio-specific, appended after "limit" for from_arg_list compat
489    arg_types = {"this": True, "expression": True, "limit": False, "mode": False}
490
491
492class RegexpSubstr(Expression, Func):
493    arg_types = {
494        "this": True,
495        "expression": True,
496        "position": False,
497        "occurrence": False,
498        "parameters": False,
499        "group": False,
500    }
501
502
503# Hashing / cryptographic
504
505
506class Compress(Expression, Func):
507    arg_types = {"this": True, "method": False}
508
509
510class Decrypt(Expression, Func):
511    arg_types = {
512        "this": True,
513        "passphrase": True,
514        "aad": False,
515        "encryption_method": False,
516        "safe": False,
517    }
518
519
520class DecryptRaw(Expression, Func):
521    arg_types = {
522        "this": True,
523        "key": True,
524        "iv": True,
525        "aad": False,
526        "encryption_method": False,
527        "aead": False,
528        "safe": False,
529    }
530
531
532class DecompressBinary(Expression, Func):
533    arg_types = {"this": True, "method": True}
534
535
536class DecompressString(Expression, Func):
537    arg_types = {"this": True, "method": True}
538
539
540class Encrypt(Expression, Func):
541    arg_types = {"this": True, "passphrase": True, "aad": False, "encryption_method": False}
542
543
544class EncryptRaw(Expression, Func):
545    arg_types = {"this": True, "key": True, "iv": True, "aad": False, "encryption_method": False}
546
547
548class CityHash64(Expression, Func):
549    arg_types = {"expressions": False}
550    is_var_len_args = True
551
552
553class FarmFingerprint(Expression, Func):
554    arg_types = {"expressions": True}
555    is_var_len_args = True
556    _sql_names = ["FARM_FINGERPRINT", "FARMFINGERPRINT64"]
557
558
559class MD5(Expression, Func):
560    _sql_names = ["MD5"]
561
562
563class MD5Digest(Expression, Func):
564    arg_types = {"this": True, "expressions": False}
565    is_var_len_args = True
566    _sql_names = ["MD5_DIGEST"]
567
568
569class MD5NumberLower64(Expression, Func):
570    pass
571
572
573class MD5NumberUpper64(Expression, Func):
574    pass
575
576
577class SHA(Expression, Func):
578    _sql_names = ["SHA", "SHA1"]
579
580
581class SHA1Digest(Expression, Func):
582    pass
583
584
585class SHA2(Expression, Func):
586    _sql_names = ["SHA2"]
587    arg_types = {"this": True, "length": False}
588
589
590class SHA2Digest(Expression, Func):
591    arg_types = {"this": True, "length": False}
592
593
594class StandardHash(Expression, Func):
595    arg_types = {"this": True, "expression": False}
596
597
598# Parse
599
600
601class ParseBignumeric(Expression, Func):
602    pass
603
604
605class ParseNumeric(Expression, Func):
606    pass
607
608
609class ParseUrl(Expression, Func):
610    arg_types = {"this": True, "part_to_extract": False, "key": False, "permissive": False}