String Expressions¶

All string operations are valid for both scalars and columns.

`StringValue` ¶

Bases: Value

Functions¶

`ascii_str()` ¶

Return the numeric ASCII code of the first character of a string.

Returns:

Type	Description
`IntegerValue`	ASCII code of the first character of the input

`authority()` ¶

Parse a URL and extract authority.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # user:pass@example.com:80

Returns:

Type	Description
`StringValue`	Extracted string value

`capitalize()` ¶

Capitalize the input string.

Returns:

Type	Description
`StringValue`	Capitalized string

`concat(other, *args)` ¶

Concatenate strings.

Parameters:

Name	Type	Description	Default
`other`	`str \| StringValue`	String to concatenate	required
`args`	`str \| StringValue`	Additional strings to concatenate	`()`

Returns:

Type	Description
`StringValue`	All strings concatenated

`contains(substr)` ¶

Return whether the expression contains substr.

Parameters:

Name	Type	Description	Default
`substr`	`str \| StringValue`	Substring for which to check	required

Returns:

Type	Description
`BooleanValue`	Boolean indicating the presence of `substr` in the expression

`convert_base(from_base, to_base)` ¶

Convert a string representing an integer from one base to another.

Parameters:

Name	Type	Description	Default
`from_base`	`int \| ir.IntegerValue`	Numeric base of the expression	required
`to_base`	`int \| ir.IntegerValue`	New base	required

Returns:

Type	Description
`IntegerValue`	Converted expression

`endswith(end)` ¶

Determine if self ends with end.

Parameters:

Name	Type	Description	Default
`end`	`str \| StringValue`	Suffix to check for	required

Examples:

>>> import ibis
>>> text = ibis.literal('Ibis project')
>>> result = text.endswith('project')

Returns:

Type	Description
`BooleanValue`	Boolean indicating whether `self` ends with `end`

`file()` ¶

Parse a URL and extract file.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.authority()  # docs/books/tutorial/index.html?name=networking

Returns:

Type	Description
`StringValue`	Extracted string value

`find(substr, start=None, end=None)` ¶

Return the position of the first occurence of substring.

Parameters:

Name	Type	Description	Default
`substr`	`str \| StringValue`	Substring to search for	required
`start`	`int \| ir.IntegerValue \| None`	Zero based index of where to start the search	`None`
`end`	`int \| ir.IntegerValue \| None`	Zero based index of where to stop the search. Currently not implemented.	`None`

Returns:

Type	Description
`IntegerValue`	Position of `substr` in `arg` starting from `start`

`find_in_set(str_list)` ¶

Find the first occurence of str_list within a list of strings.

No string in str_list can have a comma.

Parameters:

Name	Type	Description	Default
`str_list`	`Sequence[str]`	Sequence of strings	required

Examples:

>>> import ibis
>>> table = ibis.table(dict(string_col='string'))
>>> result = table.string_col.find_in_set(['a', 'b'])

Returns:

Type	Description
`IntegerValue`	Position of `str_list` in `self`. Returns -1 if `self` isn't found or if `self` contains `','`.

`fragment()` ¶

Parse a URL and extract fragment identifier.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/#DOWNLOADING")
>>> result = url.fragment()  # DOWNLOADING

Returns:

Type	Description
`StringValue`	Extracted string value

`hashbytes(how='sha256')` ¶

Compute the binary hash value of the input.

Parameters:

Name	Type	Description	Default
`how`	`Literal['md5', 'sha1', 'sha256', 'sha512']`	Hash algorithm to use	`'sha256'`

Returns:

Type	Description
`BinaryValue`	Binary expression

`host()` ¶

Parse a URL and extract host.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # example.com

Returns:

Type	Description
`StringValue`	Extracted string value

`ilike(patterns)` ¶

Match patterns against self, case-insensitive.

This function is modeled after SQL's ILIKE directive. Use % as a multiple-character wildcard or _ as a single-character wildcard.

Use re_search or rlike for regular expression-based matching.

Parameters:

Name	Type	Description	Default
`patterns`	`str \| StringValue \| Iterable[str \| StringValue]`	If `pattern` is a list, then if any pattern matches the input then the corresponding row in the output is `True`.	required

Returns:

Type	Description
`BooleanValue`	Column indicating matches

`join(strings)` ¶

Join a list of strings using self as the separator.

Parameters:

Name	Type	Description	Default
`strings`	`Sequence[str \| StringValue]`	Strings to join with `arg`	required

Examples:

>>> import ibis
>>> sep = ibis.literal(',')
>>> result = sep.join(['a', 'b', 'c'])

Returns:

Type	Description
`StringValue`	Joined string

`left(nchars)` ¶

Return the nchars left-most characters.

Parameters:

Name	Type	Description	Default
`nchars`	`int \| ir.IntegerValue`	Maximum number of characters to return	required

Returns:

Type	Description
`StringValue`	Characters from the start

`length()` ¶

Compute the length of a string.

Returns:

Type	Description
`IntegerValue`	The length of the input

`like(patterns)` ¶

Match patterns against self, case-sensitive.

This function is modeled after the SQL LIKE directive. Use % as a multiple-character wildcard or _ as a single-character wildcard.

Use re_search or rlike for regular expression-based matching.

Parameters:

Name	Type	Description	Default
`patterns`	`str \| StringValue \| Iterable[str \| StringValue]`	If `pattern` is a list, then if any pattern matches the input then the corresponding row in the output is `True`.	required

Returns:

Type	Description
`BooleanValue`	Column indicating matches

`lower()` ¶

Convert string to all lowercase.

Returns:

Type	Description
`StringValue`	Lowercase string

`lpad(length, pad=' ')` ¶

Pad arg by truncating on the right or padding on the left.

Parameters:

Name	Type	Description	Default
`length`	`int \| ir.IntegerValue`	Length of output string	required
`pad`	`str \| StringValue`	Pad character	`' '`

Returns:

Type	Description
`StringValue`	Padded string

Examples:

>>> import ibis
>>> short_str = ibis.literal("a")
>>> result = short_str.lpad(5, "-")  # ----a
>>> long_str = ibis.literal("abcdefg")
>>> result = long_str.lpad(5, "-")  # abcde

`lstrip()` ¶

Remove whitespace from the left side of string.

Returns:

Type	Description
`StringValue`	Left-stripped string

`parse_url(extract, key=None)` ¶

Parse a URL and extract its components.

key can be used to extract query values when extract == 'QUERY'

Parameters:

Name	Type	Description	Default
`extract`	`Literal['PROTOCOL', 'AUTHORITY', 'USERINFO', 'HOST', 'FILE', 'PATH', 'QUERY', 'REF']`	Component of URL to extract	required
`key`	`str \| None`	Query component to extract	`None`

Examples:

>>> import ibis
>>> url = ibis.literal("https://www.youtube.com/watch?v=kEuEcWfewf8&t=10")
>>> result = url.parse_url('QUERY', 'v')  # kEuEcWfewf

Returns:

Type	Description
`StringValue`	Extracted string value

`path()` ¶

Parse a URL and extract path.

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.authority()  # docs/books/tutorial/index.html

Returns:

Type	Description
`StringValue`	Extracted string value

`protocol()` ¶

Parse a URL and extract protocol.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.protocol()  # https

Returns:

Type	Description
`StringValue`	Extracted string value

`query(key=None)` ¶

Parse a URL and returns query strring or query string parameter.

If key is passed, return the value of the query string parameter named. If key is absent, return the query string.

Parameters:

Name	Type	Description	Default
`key`	`str \| StringValue \| None`	Query component to extract	`None`

Examples:

>>> import ibis
>>> url = ibis.literal("https://example.com:80/docs/books/tutorial/index.html?name=networking")
>>> result = url.query()  # name=networking
>>> query_name = url.query('name')  # networking

Returns:

Type	Description
`StringValue`	Extracted string value

`re_extract(pattern, index)` ¶

Return the specified match at index from a regex pattern.

Parameters:

Name Type Description Default

pattern

str | StringValue

Reguar expression pattern string

required

index

int | ir.IntegerValue

The index of the match group to return.

The behavior of this function follows the behavior of Python's re.match: when index is zero and there's a match, return the entire string, otherwise return the content of the index-th match group.

required

Returns:

Type	Description
`StringValue`	Extracted match or whole string if `index` is zero

`re_replace(pattern, replacement)` ¶

Replace match found by regex pattern with replacement.

Parameters:

Name	Type	Description	Default
`pattern`	`str \| StringValue`	Regular expression string	required
`replacement`	`str \| StringValue`	Replacement string or regular expression	required

Examples:

>>> import ibis
>>> str_literal = ibis.literal("aaabbbaaa")
>>> result = str_literal.re_replace("(b+)", r"<\1>")  # aaa<bbb>aaa

Returns:

Type	Description
`StringValue`	Modified string

`re_search(pattern)` ¶

Return whether the values match pattern.

Returns True if the regex matches a string and False otherwise.

Parameters:

Name	Type	Description	Default
`pattern`	`str \| StringValue`	Regular expression use for searching	required

Returns:

Type	Description
`BooleanValue`	Indicator of matches

`repeat(n)` ¶

Repeat a string n times.

Parameters:

Name	Type	Description	Default
`n`	`int \| ir.IntegerValue`	Number of repetitions	required

Returns:

Type	Description
`StringValue`	Repeated string

`replace(pattern, replacement)` ¶

Replace each exact match of pattern with replacement.

Parameters:

Name	Type	Description	Default
`pattern`	`StringValue`	String pattern	required
`replacement`	`StringValue`	String replacement	required

Examples:

>>> import ibis
>>> str_literal = ibis.literal("aaabbbaaa")
>>> result = str_literal.replace("aaa", "ccc")  # cccbbbccc

Returns:

Type	Description
`StringValue`	Replaced string

`reverse()` ¶

Reverse the characters of a string.

Returns:

Type	Description
`StringValue`	Reversed string

`right(nchars)` ¶

Return up to nchars from the end of each string.

Parameters:

Name	Type	Description	Default
`nchars`	`int \| ir.IntegerValue`	Maximum number of characters to return	required

Returns:

Type	Description
`StringValue`	Characters from the end

`rpad(length, pad=' ')` ¶

Pad self by truncating or padding on the right.

Parameters:

Name	Type	Description	Default
`self`		String to pad	required
`length`	`int \| ir.IntegerValue`	Length of output string	required
`pad`	`str \| StringValue`	Pad character	`' '`

Examples:

>>> import ibis
>>> short_str = ibis.literal("a")
>>> result = short_str.lpad(5, "-")  # a----
>>> long_str = ibis.literal("abcdefg")
>>> result = long_str.lpad(5, "-")  # abcde

Returns:

Type	Description
`StringValue`	Padded string

`rstrip()` ¶

Remove whitespace from the right side of string.

Returns:

Type	Description
`StringValue`	Right-stripped string

`split(delimiter)` ¶

Split as string on delimiter.

Parameters:

Name	Type	Description	Default
`delimiter`	`str \| StringValue`	Value to split by	required

Returns:

Type	Description
`ArrayValue`	The string split by `delimiter`

`startswith(start)` ¶

Determine whether self starts with end.

Parameters:

Name	Type	Description	Default
`start`	`str \| StringValue`	prefix to check for	required

Examples:

>>> import ibis
>>> text = ibis.literal('Ibis project')
>>> result = text.startswith('Ibis')

Returns:

Type	Description
`BooleanValue`	Boolean indicating whether `self` starts with `start`

`strip()` ¶

Remove whitespace from left and right sides of a string.

Returns:

Type	Description
`StringValue`	Stripped string

`substr(start, length=None)` ¶

Extract a substring.

Parameters:

Name	Type	Description	Default
`start`	`int \| ir.IntegerValue`	First character to start splitting, indices start at 0	required
`length`	`int \| ir.IntegerValue \| None`	Maximum length of each substring. If not supplied, searches the entire string	`None`

Returns:

Type	Description
`StringValue`	Found substring

`to_timestamp(format_str)` ¶

Parse a string and return a timestamp.

Parameters:

Name	Type	Description	Default
`format_str`	`str`	Format string in `strptime` format	required

Examples:

>>> import ibis
>>> date_as_str = ibis.literal('20170206')
>>> result = date_as_str.to_timestamp('%Y%m%d')

Returns:

Type	Description
`TimestampValue`	Parsed timestamp value

`translate(from_str, to_str)` ¶

Replace from_str characters in self characters in to_str.

To avoid unexpected behavior, from_str should be shorter than to_str.

Parameters:

Name	Type	Description	Default
`from_str`	`StringValue`	Characters in `arg` to replace	required
`to_str`	`StringValue`	Characters to use for replacement	required

Returns:

Type	Description
`StringValue`	Translated string

Examples:

>>> import ibis
>>> table = ibis.table(dict(string_col='string'))
>>> result = table.string_col.translate('a', 'b')

`upper()` ¶

Convert string to all uppercase.

Returns:

Type	Description
`StringValue`	Uppercase string

`userinfo()` ¶

Parse a URL and extract user info.

Examples:

>>> import ibis
>>> url = ibis.literal("https://user:pass@example.com:80/docs/books")
>>> result = url.authority()  # user:pass

Returns:

Type	Description
`StringValue`	Extracted string value

Last update: August 5, 2022

String Expressions¶

StringValue ¶

Functions¶

ascii_str() ¶

authority() ¶

capitalize() ¶

concat(other, *args) ¶

contains(substr) ¶

convert_base(from_base, to_base) ¶

endswith(end) ¶

file() ¶

find(substr, start=None, end=None) ¶

find_in_set(str_list) ¶

fragment() ¶

hashbytes(how='sha256') ¶

host() ¶

ilike(patterns) ¶

join(strings) ¶

left(nchars) ¶

length() ¶

like(patterns) ¶

lower() ¶

lpad(length, pad=' ') ¶

lstrip() ¶

parse_url(extract, key=None) ¶

path() ¶

protocol() ¶

query(key=None) ¶

re_extract(pattern, index) ¶

re_replace(pattern, replacement) ¶

re_search(pattern) ¶

repeat(n) ¶

replace(pattern, replacement) ¶

reverse() ¶

right(nchars) ¶

rpad(length, pad=' ') ¶

rstrip() ¶

split(delimiter) ¶

startswith(start) ¶

strip() ¶

substr(start, length=None) ¶

to_timestamp(format_str) ¶

translate(from_str, to_str) ¶

upper() ¶

userinfo() ¶

`StringValue` ¶

`ascii_str()` ¶

`authority()` ¶

`capitalize()` ¶

`concat(other, *args)` ¶

`contains(substr)` ¶

`convert_base(from_base, to_base)` ¶

`endswith(end)` ¶

`file()` ¶

`find(substr, start=None, end=None)` ¶

`find_in_set(str_list)` ¶

`fragment()` ¶

`hashbytes(how='sha256')` ¶

`host()` ¶

`ilike(patterns)` ¶

`join(strings)` ¶

`left(nchars)` ¶

`length()` ¶

`like(patterns)` ¶

`lower()` ¶

`lpad(length, pad=' ')` ¶

`lstrip()` ¶

`parse_url(extract, key=None)` ¶

`path()` ¶

`protocol()` ¶

`query(key=None)` ¶

`re_extract(pattern, index)` ¶

`re_replace(pattern, replacement)` ¶

`re_search(pattern)` ¶

`repeat(n)` ¶

`replace(pattern, replacement)` ¶

`reverse()` ¶

`right(nchars)` ¶

`rpad(length, pad=' ')` ¶

`rstrip()` ¶

`split(delimiter)` ¶

`startswith(start)` ¶

`strip()` ¶

`substr(start, length=None)` ¶

`to_timestamp(format_str)` ¶

`translate(from_str, to_str)` ¶

`upper()` ¶

`userinfo()` ¶