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,  # for transpilation target behavior
439    }
440
441
442class RegexpExtractAll(Expression, Func):
443    arg_types = {
444        "this": True,
445        "expression": True,
446        "group": False,
447        "parameters": False,
448        "position": False,
449        "occurrence": False,
450    }
451
452
453class RegexpFullMatch(Expression, Binary, Predicate, Func):
454    arg_types = {"this": True, "expression": True, "options": False}
455
456
457class RegexpILike(Expression, Binary, Predicate, Func):
458    arg_types = {"this": True, "expression": True, "flag": False}
459
460
461class RegexpInstr(Expression, Func):
462    arg_types = {
463        "this": True,
464        "expression": True,
465        "position": False,
466        "occurrence": False,
467        "option": False,
468        "parameters": False,
469        "group": False,
470    }
471
472
473class RegexpReplace(Expression, Func):
474    arg_types = {
475        "this": True,
476        "expression": True,
477        "replacement": False,
478        "position": False,
479        "occurrence": False,
480        "modifiers": False,
481        "single_replace": False,
482    }
483
484
485class RegexpSplit(Expression, Func):
486    # "mode" is Dremio-specific, appended after "limit" for from_arg_list compat
487    arg_types = {"this": True, "expression": True, "limit": False, "mode": False}
488
489
490class RegexpSubstr(Expression, Func):
491    arg_types = {
492        "this": True,
493        "expression": True,
494        "position": False,
495        "occurrence": False,
496        "parameters": False,
497        "group": False,
498    }
499
500
501# Hashing / cryptographic
502
503
504class Compress(Expression, Func):
505    arg_types = {"this": True, "method": False}
506
507
508class Decrypt(Expression, Func):
509    arg_types = {
510        "this": True,
511        "passphrase": True,
512        "aad": False,
513        "encryption_method": False,
514        "safe": False,
515    }
516
517
518class DecryptRaw(Expression, Func):
519    arg_types = {
520        "this": True,
521        "key": True,
522        "iv": True,
523        "aad": False,
524        "encryption_method": False,
525        "aead": False,
526        "safe": False,
527    }
528
529
530class DecompressBinary(Expression, Func):
531    arg_types = {"this": True, "method": True}
532
533
534class DecompressString(Expression, Func):
535    arg_types = {"this": True, "method": True}
536
537
538class Encrypt(Expression, Func):
539    arg_types = {"this": True, "passphrase": True, "aad": False, "encryption_method": False}
540
541
542class EncryptRaw(Expression, Func):
543    arg_types = {"this": True, "key": True, "iv": True, "aad": False, "encryption_method": False}
544
545
546class CityHash64(Expression, Func):
547    arg_types = {"expressions": False}
548    is_var_len_args = True
549
550
551class FarmFingerprint(Expression, Func):
552    arg_types = {"expressions": True}
553    is_var_len_args = True
554    _sql_names = ["FARM_FINGERPRINT", "FARMFINGERPRINT64"]
555
556
557class MD5(Expression, Func):
558    _sql_names = ["MD5"]
559
560
561class MD5Digest(Expression, Func):
562    arg_types = {"this": True, "expressions": False}
563    is_var_len_args = True
564    _sql_names = ["MD5_DIGEST"]
565
566
567class MD5NumberLower64(Expression, Func):
568    pass
569
570
571class MD5NumberUpper64(Expression, Func):
572    pass
573
574
575class SHA(Expression, Func):
576    _sql_names = ["SHA", "SHA1"]
577
578
579class SHA1Digest(Expression, Func):
580    pass
581
582
583class SHA2(Expression, Func):
584    _sql_names = ["SHA2"]
585    arg_types = {"this": True, "length": False}
586
587
588class SHA2Digest(Expression, Func):
589    arg_types = {"this": True, "length": False}
590
591
592class StandardHash(Expression, Func):
593    arg_types = {"this": True, "expression": False}
594
595
596# Parse
597
598
599class ParseBignumeric(Expression, Func):
600    pass
601
602
603class ParseNumeric(Expression, Func):
604    pass
605
606
607class ParseUrl(Expression, Func):
608    arg_types = {"this": True, "part_to_extract": False, "key": False, "permissive": False}