Skip to content

String operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Server-side read, modify, and type-conversion operations for String bins, invoked through the operate API to search, transform, extract, and normalize text without fetch-modify-write round-trips. For conceptual guidance, UTF-8 validation, and worked examples, see the String operations overview.

Every operation on this page also has an expression form, which evaluates to a value instead of writing it. See String expressions for those, and Operations and expressions for which to reach for.

String operations require Aerospike Database 8.2.0 or later. Earlier versions do not recognize the opcodes and reject the command. Each operation lists the version it was introduced in.

Unicode semantics

String operations treat bin values as UTF-8 text:

  • strlen counts Unicode codepoints; byte_length counts UTF-8 bytes.
  • substr, char_at, insert, and snip take codepoint indexes. Negative indexes count from the end of the string, and out-of-range indexes are clamped to [0, length].
  • Substring matching in find, contains, starts_with, ends_with, replace, and replace_all treats canonically equivalent text as equal, so precomposed é (U+00E9) matches e followed by combining acute (U+0301).
  • Expression comparison operators (eq, ne, gt, ge, lt, le) compare String values by UTF-8 bytes and do not treat those spellings as equal. See Compare String values.

When both the bin value and all arguments are ASCII, the server operates directly on bytes instead of converting to UTF-16 for processing. No client configuration is required.

Context

Every operation except to_string takes an optional context path selecting a String nested inside a List or Map bin. Omit it to target the bin value itself.

A modify operation against a missing bin is not an error: insert, concat, append, prepend, overwrite, repeat, pad_start, and pad_end create it, and every other modify operation leaves the record unchanged and returns success.

A bin created this way starts from an empty string, so the stored result is whatever the operation produces from "". concat, append, prepend, insert, and overwrite store just their operand; pad_start and pad_end store only pad text. repeat is the exception: repeating an empty string leaves it empty for any count, so the bin is created and holds "". It succeeds and returns no value, so that outcome is indistinguishable from a bin that was already empty.

A missing nested path behaves differently. If the path does not resolve, the operation returns AS_ERR_OP_NOT_APPLICABLE; the eight operations above create a missing bin, not a missing nested path. Set NO_FAIL to turn an unresolved path into a success that writes nothing. A malformed path returns AS_ERR_PARAMETER with subcode AS_SUB_PARAM_STRING_CTX_MALFORMED.

Operation flags

Modify operations accept write flags per operation: a StringWriteFlags int in Java, a StringPolicy in Python, and an as_string_policy in C. Read operations take no write flags and always return an error on failure. The regex flags on regex_compare and regex_replace, and the numeric_type argument on is_numeric, are operation arguments rather than write flags.

The policy argument precedes the context path. A positional call that omits the policy binds the context path to the policy parameter, so the operation targets the top-level bin instead of the nested string.

FlagValueEffect
CREATE_ONLY0x01Apply the operation only if the bin does not already exist. Valid on the eight operations that create a missing bin; the other 11 modify operations reject it. Cannot be combined with UPDATE_ONLY, and not accepted with a context path.
UPDATE_ONLY0x02Apply the operation only if the bin already exists. Valid on all modify operations.
NO_FAIL0x04Return success and leave the bin unchanged instead of failing. Modify operations only. Read operations have no write flags. See the lists below for which failures it suppresses.

NO_FAIL suppresses these failures:

NO_FAIL does not suppress these:

  • AS_ERR_INCOMPATIBLE_TYPE from applying a modify operation to a bin that is not a String.
  • AS_ERR_INVALID_ENCODING, either from invalid UTF-8 in the stored value or from a modify result that is not valid UTF-8.
  • Malformed or unparseable arguments, including invalid UTF-8 in an argument.
  • Write flags that are not valid for the operation: CREATE_ONLY on an operation that cannot create a bin, CREATE_ONLY together with UPDATE_ONLY, or CREATE_ONLY with a context path. Each returns AS_ERR_PARAMETER with subcode AS_SUB_PARAM_STRING_OP_PARAMS_INVALID.

Both lists contain cases that return AS_ERR_PARAMETER, so the error code alone does not tell you whether NO_FAIL would have suppressed a failure. Use the lists rather than the code.

What a suppressed operation leaves behind

A suppressed operation leaves the bin holding the value it had before the operation ran. It does not clear the bin and does not store a null. Because modify operations return no value either way, a suppressed operation and an applied one look identical in the response. Read the bin to tell them apart.

NO_FAIL is not a way to modify a bin whose type you do not know. A non-String bin still returns AS_ERR_INCOMPATIBLE_TYPE. Gate the write with a bin-type filter expression, or handle the error.

Reading strings

Read operations inspect or extract data from a String bin without modifying the stored value.

Empty operands

An empty needle is an error only on replace and replace_all. Every read operation that takes a needle answers successfully instead, treating the empty string as matching at the start of any value:

CallResult
find(bin, "")0
find("", needle)-1
contains(bin, "")true
starts_with(bin, "") / ends_with(bin, "")true
starts_with("", prefix) / ends_with("", suffix)false
regex_compare(bin, "")true

A caller that treats an empty search term as invalid input must reject it before the operation, because the server will not.

Modifying strings

Modify operations transform the String bin in place and return no value. To read the mutated string, add a read operation for the same bin to the same operate() call.

The response then carries an entry for each operation on that bin, and clients differ in how an accessor reaches it: by the operation’s position, by index into a list held under the bin name, or by bin name alone, where the read’s entry replaces the modify’s. In C both entries are present, but as_record_get and the typed accessors answer with the first — the modify’s nil — so iterate rec.bins.entries to reach the value.

try (RecordStream rs = session.upsert(key)
    .bin("email").upper()
    .bin("email").get()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // One slot per operation, reached by position.
    String updated = rec.operationResult(1).getString();
}

to_string is the exception: it dispatches as a read operation and does return the converted string.

Result size limits

Two separate limits apply to a modify operation, and they fail differently:

  • Per-operation result cap: 8 MiB. A modify operation whose result would exceed 8 MiB fails with AS_ERR_PARAMETER (subcode AS_SUB_PARAM_STRING_OP_PARAMS_INVALID) before it runs. The limit is applied to an upper-bound estimate rather than to the finished string, so an operation can be rejected when its actual result would have fit.
  • Record size limit. A result that clears the per-operation cap is then subject to the namespace max-record-size when the record is written, which fails with AS_ERR_RECORD_TOO_BIG.

The per-operation cap is checked first, so an oversized transform surfaces as a parameter error rather than a record-size error. Setting NO_FAIL suppresses that rejection: the operation returns success and the bin keeps its previous value, so a write that was too large to apply is indistinguishable from one that succeeded.

A doc bin holding 1 KiB repeated 10,000 times would pass 8 MiB. With NO_FAIL set, each of these calls succeeds and leaves doc at its original 1 KiB:

try (RecordStream rs = session.upsert(key)
    .bin("doc").repeat(10000, StringWriteOptions::noFail)
    .execute()) {
    rs.next().recordOrThrow();
}

Without NO_FAIL, the same call fails with AS_ERR_PARAMETER, which is the only signal that the transform did not happen.

Converting to string

to_string converts integer, float, boolean, blob, or string bins to a string representation without requiring the client to know the bin type in advance.

Error codes

ErrorTypical cause
AS_ERR_INCOMPATIBLE_TYPEOperation applied to a non-String bin (or wrong type for to_string)
AS_ERR_INVALID_ENCODINGString bin contains invalid UTF-8 at operation time
AS_ERR_PARAMETERInvalid argument: invalid UTF-8 in an operation argument, an invalid or rejected regex pattern, an unrecognized regex flag bit, a write flag that is not valid for the operation, an empty needle on replace or replace_all, a negative repeat count or pad length, an out-of-range overwrite index, or a result that would exceed the per-operation size limit
AS_ERR_OP_NOT_APPLICABLEOperation cannot be applied to this value: a numeric parse failure or overflow, to_string on a non-UTF-8 blob, invalid base64, or a regex complexity limit
AS_ERR_BIN_EXISTSThe bin already exists and the operation carries CREATE_ONLY
AS_ERR_RECORD_TOO_BIGThe written record exceeds the max-record-size limit

The same errors can surface when string bin expressions run in filters or operate projections. Filter expressions that evaluate to unknown exclude the record from query results.

See Error codes for the full list.

Error detail subcodes

When a client asks for error details, a failure carries a machine-readable subcode alongside the human-readable message. The error-details-max-verbosity service configuration parameter caps how much detail the server returns. Each subcode belongs to exactly one status, and published values are never renumbered or reused, so you can match on them.

Subcodes paired with AS_ERR_PARAMETER:

SubcodeValueCondition
AS_SUB_PARAM_STRING_OP_PARAMS_INVALID6Arguments malformed or out of range, including invalid regex flag bits
AS_SUB_PARAM_STRING_OP_INVALID7Unrecognized operation code, or a read operation sent on the modify path
AS_SUB_PARAM_STRING_CTX_MALFORMED8Malformed context path
AS_SUB_PARAM_STRING_INDEX_OUT_OF_BOUNDS9Index or codepoint range out of bounds, as with overwrite
AS_SUB_PARAM_STRING_REGEX_INVALID10Regex pattern is not valid ICU syntax
AS_SUB_PARAM_STRING_UTF8_INVALID11A string argument is not valid UTF-8

Subcodes paired with AS_ERR_OP_NOT_APPLICABLE:

SubcodeValueCondition
AS_SUB_OPNOT_STRING_CONVERSION_FAILED10to_integer or to_double could not parse the string, including numeric overflow
AS_SUB_OPNOT_STRING_UTF8_INVALID11Source blob or string is not valid UTF-8
AS_SUB_OPNOT_STRING_REGEX_LIMIT_EXCEEDED12Regex match or replace exhausted an engine budget
AS_SUB_OPNOT_STRING_B64_INVALID13Value is not valid base64

Failures that the status alone identifies, such as AS_ERR_INCOMPATIBLE_TYPE, report AS_SUB_NONE (0) and carry the distinguishing detail in the message text.

Modify operations

append

create_only update_only no_fail 
append(bin, value[, policy][, context])
Description

Appends value to the string bin (Unicode-aware).

Arguments
NameTypeDescription
binstring

Name of bin.

valuestring

Text to append.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_append

Examples
Append to the end

A record stores a running log line in a String bin called log. Given log = "start", calling append("log", " line") leaves the bin holding "start line".

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("log").append(" line")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

case_fold

update_only no_fail 
case_fold(bin[, policy][, context])
Description

Applies Unicode case folding for case-insensitive comparison.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_case_fold

Examples
Fold case for comparison

Case folding normalizes a value for caseless comparison, and is not the same as lowercasing. Given name = "Straße", calling case_fold("name") leaves the bin holding "strasse": the sharp s expands to two characters, so the string gets longer.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("name").caseFold()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

concat

create_only update_only no_fail 
concat(bin, value[, policy][, context])
Description

Concatenates additional string values onto the bin.

Arguments
NameTypeDescription
binstring

Name of bin.

valuestring

String values to append to the bin, in order. The server operation takes a list. Python accepts a list only, and Java and C also provide a single-value form.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_concat

Examples
Join a fragment onto the value

A record stores a label list in a String bin called tags. Given tags = "red", calling concat("tags", ",green") leaves the bin holding "red,green".

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("tags").concat(",green")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

insert

create_only update_only no_fail 
insert(bin, offset, value[, policy][, context])
Description

Inserts value at codepoint offset.

Arguments
NameTypeDescription
binstring

Name of bin.

offsetinteger

Codepoint index at which to insert. Negative values count from the end of the string. Out-of-range values are clamped to [0, length], so an offset equal to the length appends.

valuestring

Text to insert.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_insert

Examples
Insert at a codepoint offset

Given text = "hi", calling insert("text", 1, "oh") leaves the bin holding "hohi". The offset is a codepoint index, so the new text lands before the character currently at that position.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("text").insert(1, "oh")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

lower

update_only no_fail 
lower(bin[, policy][, context])
Description

Converts the String bin to lowercase.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_lower

Examples
Lowercase a value

A record stores an address a user typed into a form, in a String bin called email. Given email = "Ana@Corp.IO", calling lower("email") leaves the bin holding "ana@corp.io".

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("email").lower()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

normalize_nfc

update_only no_fail 
normalize_nfc(bin[, policy][, context])
Description

Normalizes the String bin to Unicode NFC form. Normalize stored values before comparing them with NFC literals using the eq expression. See Compare String values.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_normalize_nfc

Examples
Normalize to composed form

The same text can be stored two ways: a precomposed é (U+00E9), or an e followed by a combining acute accent (U+0301). Given name holding the two-codepoint decomposed form, calling normalize_nfc("name") leaves the bin holding the single precomposed codepoint, so strlen drops from 2 to 1.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("name").normalizeNfc()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

overwrite

create_only update_only no_fail 
overwrite(bin, offset, value[, policy][, context])
Description

Overwrites the string bin starting at codepoint offset with value.

Arguments
NameTypeDescription
binstring

Name of bin.

offsetinteger

Codepoint index at which to start overwriting. Negative values count from the end of the string, as they do for insert, char_at, substr, and snip. The resolved index must satisfy 0 <= offset < length; outside that range the operation returns AS_ERR_PARAMETER with subcode AS_SUB_PARAM_STRING_INDEX_OUT_OF_BOUNDS rather than being clamped. Unlike insert, overwrite cannot target an offset equal to the string length, because it carries no fill text for the gap that would leave. On an empty or missing bin the only accepted offset is 0, which writes value as the new bin contents.

valuestring

Replacement text.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_overwrite

Examples
Replace text at a fixed position

Given text = "2026-01-01", calling overwrite("text", 5, "12") leaves the bin holding "2026-12-01". The replacement is written in place and the string length does not change.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("text").overwrite(5, "12")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

pad_end

create_only update_only no_fail 
pad_end(bin, target_length, pad_string[, policy][, context])
Description

Pads the end of the string bin to target_length using pad_string.

Arguments
NameTypeDescription
binstring

Name of bin.

target_lengthinteger

Minimum codepoint length after padding. Must be non-negative. Padding adds exactly enough codepoints to reach this length.

pad_stringstring

Padding string. Must not be empty. A multi-codepoint pad repeats to fill the gap and is truncated mid-pattern to reach target_length exactly, so padding "xyz" to 8 with "ab" yields "xyzababa".

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_pad_end

Examples
Pad to a fixed width

Given id = "42", calling pad_end("id", 6, "0") leaves the bin holding "420000". A value already at or beyond the target length is left unchanged.

Padding shorter than a whole repetition

The pad repeats whole, then a prefix of it fills the remainder. Padding "xyz" to 8 codepoints with "ab" needs 5 pad codepoints, so the pad block is "ab" + "ab" + "a" and the result is "xyzababa". The truncated fragment lands at the end of the string, not next to the original text.

A negative target_length or an empty pad_string returns AS_ERR_PARAMETER with subcode AS_SUB_PARAM_STRING_OP_PARAMS_INVALID.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("id").padEnd(6, "0")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

pad_start

create_only update_only no_fail 
pad_start(bin, target_length, pad_string[, policy][, context])
Description

Pads the start of the string bin to target_length using pad_string.

Arguments
NameTypeDescription
binstring

Name of bin.

target_lengthinteger

Minimum codepoint length after padding. Must be non-negative. Padding adds exactly enough codepoints to reach this length.

pad_stringstring

Padding string. Must not be empty. A multi-codepoint pad repeats to fill the gap and is truncated mid-pattern to reach target_length exactly, so padding "xyz" to 8 with "ab" yields "ababaxyz".

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_pad_start

Examples
Pad to a fixed width

Given id = "42", calling pad_start("id", 6, "0") leaves the bin holding "000042". A value already at or beyond the target length is left unchanged.

Padding shorter than a whole repetition

The pad repeats whole, then a prefix of it fills the remainder. Padding "xyz" to 8 codepoints with "ab" needs 5 pad codepoints, so the pad block is "ab" + "ab" + "a" and the result is "ababaxyz". pad_end builds the same block and appends it instead, giving "xyzababa".

A negative target_length or an empty pad_string returns AS_ERR_PARAMETER with subcode AS_SUB_PARAM_STRING_OP_PARAMS_INVALID.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("id").padStart(6, "0")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

prepend

create_only update_only no_fail 
prepend(bin, value[, policy][, context])
Description

Prepends value to the string bin (Unicode-aware).

Arguments
NameTypeDescription
binstring

Name of bin.

valuestring

Text to prepend.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_prepend

Examples
Prepend to the front

A record stores a log line in a String bin called log. Given log = "started", calling prepend("log", "prefix: ") leaves the bin holding "prefix: started".

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("log").prepend("prefix: ")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

regex_replace

update_only no_fail 
regex_replace(bin, pattern, replacement[, regex_flags][, policy][, context])
Description

Replaces the first regex match in the string bin, or every match when the GLOBAL flag is set.

Arguments
NameTypeDescription
binstring

Name of bin.

patternstring

Regular expression pattern. An empty pattern is accepted rather than rejected, and matches at every position: without GLOBAL the replacement is prepended to the value, and with GLOBAL it is inserted before every codepoint and once at the end. This differs from replace and replace_all, which reject an empty needle. For the syntax the pattern is written in, see Regular expression syntax.

replacementstring

Replacement text, in ICU’s replacement dialect: $0 is the whole match, $1 a numbered capture group, ${name} a named one, and \ escapes the next character. A $ that resolves to no capture group fails the operation on any record the pattern matches; where it does not match, the replacement is never evaluated and the operation succeeds unchanged. See Replacement string syntax.

regex_flagsinteger

Regex flags, combined with bitwise OR. Defaults to none, which replaces only the first match; GLOBAL (16) replaces every match and is valid on this operation only. For the values, their effects, how AEL spells them, and why these must not be confused with the string write flags, see Regex flags. The write policy is a separate argument.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_regex_replace

Examples
Replace every match

Without GLOBAL, only the first match is replaced: on "a1 b22 c333", stripping \d+ yields "a b22 c333". Setting GLOBAL yields "a b c".

Modify operations do not return a value. To read the result, add a read operation for the same bin to the same operate() call.

Passing a policy needs all three arguments

Regex flags and the write policy are different sets, and passing one where the other belongs is silent. Beyond that, there is no 2-arg form for policy alone. The second wire argument is always consumed as regex_flags. To pass NO_FAIL (or any policy flag), send all three arguments and include regex_flags explicitly, using 0 when no regex behavior is wanted. A 1- or 2-arg send is safe when no policy is needed.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("text").regexReplace("\\d+", "", StringRegexFlags.GLOBAL)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

repeat

create_only update_only no_fail 
repeat(bin, count[, policy][, context])
Description

Repeats the string bin count times.

Arguments
NameTypeDescription
binstring

Name of bin.

countinteger

Number of times to repeat the bin value. Must be non-negative. A negative count returns AS_ERR_PARAMETER. A count of 0 is accepted and is not a no-op: it replaces the bin value with the empty string.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_repeat

Examples
Repeat the value

Given unit = "ab", calling repeat("unit", 3) leaves the bin holding "ababab". A count of 1 leaves the value unchanged.

A count of zero empties the bin

repeat(bin, 0) succeeds and writes the empty string. The bin stays present and holds "". It is not left unchanged and it is not removed. Guard the call if count comes from application input that can reach zero.

Modify operations do not return a value. To read the new string, add a read operation for the same bin to the same operate() call.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("unit").repeat(3)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

replace

update_only no_fail 
replace(bin, find, replace[, policy][, context])
Description

Replaces the first occurrence of find with replace. Treats canonically equivalent text as equal.

Arguments
NameTypeDescription
binstring

Name of bin.

findstring

Substring to replace. Must not be empty: an empty needle returns AS_ERR_PARAMETER. regex_replace differs, accepting an empty pattern and rewriting the value.

replacestring

Replacement text.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_replace

Examples
Rewrite the first match

A record stores a file location in a String bin called path. Given path = "/data/tmp/data.log", calling replace("path", "/data", "/mnt") sets the bin to "/mnt/tmp/data.log". The needle occurs twice and only the leading occurrence changes. Use replace_all to change every occurrence.

Modify operations do not return a value. To read the new string, add a read operation for the same bin to the same operate() call.

A needle that is absent still succeeds

A find value that does not occur in the string is not a miss to report: the operation returns success and leaves the value unchanged. Because modify operations return no value, that outcome is indistinguishable from a replacement that happened. Read the bin in the same operate() call when the caller needs to know whether anything changed.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("path").replace("/data", "/mnt")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

replace_all

update_only no_fail 
replace_all(bin, find, replace[, policy][, context])
Description

Replaces all occurrences of find with replace. Treats canonically equivalent text as equal.

Arguments
NameTypeDescription
binstring

Name of bin.

findstring

Substring to replace. Must not be empty: an empty needle returns AS_ERR_PARAMETER. regex_replace differs, accepting an empty pattern and rewriting the value.

replacestring

Replacement text.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_replace_all

Examples
Rewrite every match

A record stores a file location in a String bin called path. Given path = "/data/tmp/data.log", calling replace_all("path", "/data", "/mnt") sets the bin to "/mnt/tmp/mnt.log", changing both occurrences. Use replace to change only the first.

Modify operations do not return a value. To read the new string, add a read operation for the same bin to the same operate() call.

A needle that is absent still succeeds

A find value that does not occur in the string is not a miss to report: the operation returns success and leaves the value unchanged. Because modify operations return no value, that outcome is indistinguishable from a replacement that happened. Read the bin in the same operate() call when the caller needs to know whether anything changed.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("path").replaceAll("/data", "/mnt")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

snip

update_only no_fail 
snip(bin, from[, to][, policy][, context])
Description

Removes the codepoint range from from (inclusive) to to (exclusive).

Arguments
NameTypeDescription
binstring

Name of bin.

frominteger

Start codepoint index (inclusive). Negative values count from the end of the string. Out-of-range values are clamped to [0, length].

tointeger

End codepoint index (exclusive). Negative values count from the end of the string; out-of-range values are clamped to [0, length]. Optional; defaults to the string’s codepoint length, removing everything from from to the end of the string. Omitting to also drops the write flags: the shorter form carries no policy, so NO_FAIL has no effect on it. Pass to explicitly when the operation needs a flag, and use the string’s length to keep the same result.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_snip

Examples
Remove a codepoint range

Given text = "hello big world", calling snip("text", 6, 10) leaves the bin holding "hello world". The range is half-open, so the codepoint at to is kept.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("text").snip(6, 10)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

trim

update_only no_fail 
trim(bin[, policy][, context])
Description

Removes leading and trailing Unicode whitespace.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_trim

Examples
Strip surrounding whitespace

A record stores an address a user typed into a form, in a String bin called email. Trimming it server-side normalizes the value without a read and a rewrite.

Given email = " ana@corp.io ", calling trim("email") leaves the bin holding "ana@corp.io". Use trim_start or trim_end to strip only one side.

Modify operations do not return a value. To read the trimmed string, add a read operation for the same bin to the same operate() call.

Whitespace is the full Unicode set

trim strips every codepoint carrying the Unicode White_Space property, not only spaces and tabs. That includes the no-break space (U+00A0), the figure space (U+2007), and the narrow no-break space (U+202F), so text pasted from a web page or a word processor loses those too.

A value that is entirely whitespace becomes the empty string rather than staying unchanged.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("email").trim()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

trim_end

update_only no_fail 
trim_end(bin[, policy][, context])
Description

Removes trailing Unicode whitespace.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_trim_end

Examples
Strip trailing whitespace

A record stores an address a user typed into a form, in a String bin called email. Trimming only the end preserves any leading content.

Given email = " ana@corp.io ", calling trim_end("email") leaves the bin holding " ana@corp.io". The two leading spaces remain. Use trim to strip both sides.

Modify operations do not return a value. To read the trimmed string, add a read operation for the same bin to the same operate() call.

Whitespace is the full Unicode set

trim_end strips every codepoint carrying the Unicode White_Space property, not only spaces and tabs. That includes the no-break space (U+00A0), the figure space (U+2007), and the narrow no-break space (U+202F), so text pasted from a web page or a word processor loses those too.

A value that is entirely whitespace becomes the empty string rather than staying unchanged.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("email").trimEnd()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

trim_start

update_only no_fail 
trim_start(bin[, policy][, context])
Description

Removes leading Unicode whitespace.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_trim_start

Examples
Strip leading whitespace

A record stores an address a user typed into a form, in a String bin called email. Trimming only the front preserves any trailing content.

Given email = " ana@corp.io ", calling trim_start("email") leaves the bin holding "ana@corp.io ". The two trailing spaces remain. Use trim to strip both sides.

Modify operations do not return a value. To read the trimmed string, add a read operation for the same bin to the same operate() call.

Whitespace is the full Unicode set

trim_start strips every codepoint carrying the Unicode White_Space property, not only spaces and tabs. That includes the no-break space (U+00A0), the figure space (U+2007), and the narrow no-break space (U+202F), so text pasted from a web page or a word processor loses those too.

A value that is entirely whitespace becomes the empty string rather than staying unchanged.

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("email").trimStart()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

upper

update_only no_fail 
upper(bin[, policy][, context])
Description

Converts the String bin to uppercase.

Arguments
NameTypeDescription
binstring

Name of bin.

policyString policy

String write flags for the operation. Optional, and defaults to none. See Operation flags.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
none
Introduced
8.2.0
Expression form

string_upper

Examples
Uppercase a value

A record stores a display name in a String bin called name. Given name = "ana borg", calling upper("name") leaves the bin holding "ANA BORG".

Code sample 
try (RecordStream rs = session.upsert(key)
    .bin("name").upper()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

Read operations

b64_decode 

b64_decode(bin[, context])
Description

Decodes a base64-encoded string bin into a Blob.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
blob
Introduced
8.2.0
Expression form

string_b64_decode

Examples
Decode a stored payload

A record stores a base64 payload in a String bin called payload. Given payload = "aGVsbG8=", calling b64_decode("payload") returns a 5-byte Blob holding the bytes hello.

Accepted encoding

Requires standard base64 with padding. The URL-safe variant and any whitespace are rejected, including the line breaks that base64 and openssl base64 insert by default. All of these return AS_ERR_OP_NOT_APPLICABLE without distinguishing which. An empty string decodes to an empty blob.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("payload").b64Decode()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

byte_length 

byte_length(bin[, context])
Description

Returns the number of UTF-8 bytes in the string bin.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
integer
Introduced
8.2.0
Expression form

string_byte_length

Examples
Measure the stored bytes

Given email = "aná@corp.io", calling byte_length("email") returns 12, while strlen returns 11. The accented character occupies two UTF-8 bytes and one codepoint.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").byteLength()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

char_at 

char_at(bin, index[, context])
Description

Returns the single-codepoint substring at index. Supports negative indexes.

Arguments
NameTypeDescription
binstring

Name of bin.

indexinteger

Codepoint index.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
string
Introduced
8.2.0
Expression form

string_char_at

Examples
Read a character by position

A record stores a contact address in a String bin called email. Reading a single character avoids transferring the whole value when only one position matters, such as bucketing addresses by their first letter.

Given email = "ana@corp.io", calling char_at("email", 0) returns "a". A negative index counts from the end, so char_at("email", -1) returns the last codepoint, "o".

An out-of-range index does not fail

The index is clamped to [0, length] rather than rejected, and the two directions clamp to different results. "ana@corp.io" is 11 codepoints, so char_at("email", 99) clamps to the end and returns an empty string, while char_at("email", -99) clamps to 0 and returns the first codepoint, "a".

Neither returns an error, and the underflow result is a valid codepoint that is indistinguishable from a deliberate char_at("email", 0). Range-check the index before the operation when an out-of-range request must be told apart from a real character.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").charAt(0)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

contains 

contains(bin, needle[, context])
Description

Returns whether the string bin contains needle, respecting Unicode canonical equivalence.

Arguments
NameTypeDescription
binstring

Name of bin.

needlestring

Substring to search for.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_contains

Examples
Test for a substring

Given email = "ana@company.com", calling contains("email", "@company.com") returns true. Matching is anywhere in the value, not anchored to either end.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").contains("@company.com")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

ends_with 

ends_with(bin, suffix[, context])
Description

Returns whether the string bin ends with suffix. Treats canonically equivalent text as equal.

Arguments
NameTypeDescription
binstring

Name of bin.

suffixstring

Suffix to test.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_ends_with

Examples
Test a suffix

Given email = "ana@corp.com", calling ends_with("email", ".com") returns true, and ends_with("email", ".org") returns false.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").endsWith(".com")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

find 

find(bin, needle[, occurrence][, context])
Description

Returns the codepoint index of the occurrenceth match of needle, or -1 if not found. Treats canonically equivalent text as equal.

Arguments
NameTypeDescription
binstring

Name of bin.

needlestring

Substring to find.

occurrenceinteger

Match number, 1-based. Negative values count matches from the end (-1 is the last match). Matches do not overlap. Must be non-zero: 0 returns AS_ERR_PARAMETER. Optional, and defaults to 1 (first match). Clients expose the two-argument form as find and the three-argument form as find_occurrence in C, and as a defaulted parameter in Java and Python.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
integer
Introduced
8.2.0
Expression form

string_find

Examples
Locate a separator

A record stores a contact address in a String bin called email. Finding the separator lets an application split the local part from the domain without transferring the whole value.

Given email = "ana@corp.co.uk", calling find("email", "@") returns 3, the codepoint index of the match. An occurrence selects among repeats: find("email", ".") returns 8 for the first dot, and find("email", ".", -1) returns 11 for the last.

Matches do not overlap

Each match resumes after the previous one. On "aaaa" with needle "aa", occurrence 1 returns 0, 2 returns 2, and 3 returns -1, even though "aa" begins at index 0, 1, and 2. Counting matches by walking occurrence upward undercounts a needle that can overlap itself.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").find("@")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

is_lower 

is_lower(bin[, context])
Description

Returns whether the string bin is lowercase: it holds no uppercase letter and at least one lowercase letter. Digits, spaces, and punctuation are ignored rather than counted against the value. An empty string returns true.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_is_lower

Examples
Test whether a value is lowercase

A record stores a short identifier in a String bin called code. Given code = "hello", calling is_lower("code") returns true. A single uppercase letter fails the test, so "Hello" returns false.

Digits, spaces, and punctuation do not count against the value: "hello world", "abc123", and "usd$" all return true.

A value with no cased letter

A non-empty value holding no cased letter returns false, so "123", " ", and "42.5" are all false. Use is_numeric to test for a numeric value.

The empty string is the exception, and returns true.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("code").isLower()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

is_numeric 

is_numeric(bin[, numeric_type][, context])
Description

Returns whether the string bin belongs to the requested numeric class.

Arguments
NameTypeDescription
binstring

Name of bin.

numeric_typeinteger

Numeric class to test for: 0 = ANY (int-class or float-class, the default), 1 = INT (optional sign then digits only, must fit int64), 2 = FLOAT (must contain a literal . followed by at least one digit, and must fit double). The values are mutually exclusive selectors, not combinable bits; any other value returns AS_ERR_PARAMETER. Optional; defaults to ANY. Constants are NumericType in Python, StringNumericType in Java, and as_string_numeric_type in C.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_is_numeric

Examples
Test whether a value parses as a number

Given amount = "42", calling is_numeric("amount") returns true. Given amount = "42abc", it returns false. The default class accepts both integer and float forms.

Scientific notation

Float-class matching requires a literal . followed by a digit, so scientific-notation literals such as 1e5 match none of the three classes, including ANY. Do not use is_numeric to guard a to_double call: to_double parses scientific notation that is_numeric rejects.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("amount").isNumeric()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

is_upper 

is_upper(bin[, context])
Description

Returns whether the string bin is uppercase: it holds no lowercase letter and at least one uppercase letter. Digits, spaces, and punctuation are ignored rather than counted against the value. An empty string returns true.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_is_upper

Examples
Test whether a value is uppercase

A record stores a short identifier in a String bin called code. Given code = "HELLO", calling is_upper("code") returns true. A single lowercase letter fails the test, so "Hello" returns false.

Digits, spaces, and punctuation do not count against the value: "HELLO WORLD", "ABC123", and "USD$" all return true.

A value with no cased letter

A non-empty value holding no cased letter returns false, so "123", " ", and "42.5" are all false. Use is_numeric to test for a numeric value.

The empty string is the exception, and returns true.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("code").isUpper()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

regex_compare 

regex_compare(bin, pattern[, regex_flags][, context])
Description

Returns whether the string bin matches pattern, using ICU regular expression syntax.

Arguments
NameTypeDescription
binstring

Name of bin.

patternstring

Regular expression pattern, in ICU syntax. For the constructs ICU accepts, the ones it reads differently from PCRE, and the spellings it rejects at parse time, see Regular expression syntax.

regex_flagsinteger

Bit field of regex regex_flags, combinable with bitwise OR. Optional, and defaults to 0 (no regex_flags). GLOBAL is not valid here. For the values, their effects, and how AEL spells them, see Regex flags. Clients expose the two-argument form as regex_compare and the three-argument form as regex_compare_flags in C.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_regex_compare

Examples
Match against a pattern

Given email = "ana@company.com", calling regex_compare("email", "^[^@]+@company\\.com$") returns true. The pattern uses ICU syntax, and matches only where the pattern anchors it.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").regexCompare("^[^@]+@company\\.com$")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

split 

split(bin[, separator][, context])
Description

Splits the string bin into a list of strings by separator.

Arguments
NameTypeDescription
binstring

Name of bin.

separatorstring

Delimiter string. Optional. When omitted, the bin is split into one list element per Unicode codepoint. Clients expose the no-separator form as split and the separator form as split_separator in Python and C, and as an overload of split in Java.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
list
Introduced
8.2.0
Expression form

string_split

Examples
Split on a delimiter

A record stores a comma-separated label list in a String bin called tags. Splitting it server-side returns the parts as a List without the client parsing the value.

Given tags = "red,green,blue", calling split("tags", ",") returns ["red", "green", "blue"].

Empty elements and empty bins

Every separator in the value produces a boundary, so adjacent, leading, and trailing separators yield empty elements rather than being collapsed. A separator that does not occur is not an error. The two empty-bin results differ depending on whether a separator was passed.

Bin valueCallResult
"a,,b"split("tags", ",")["a", "", "b"]
",a"split("tags", ",")["", "a"]
"a,"split("tags", ",")["a", ""]
"abc"split("tags", ",")["abc"]
""split("tags", ",")[""]
""split("tags")[]
"abc"split("tags")["a", "b", "c"]

The last row is the one to watch. Omitting separator does not return the value unsplit: it returns one element per codepoint. Filtering empty elements out is the caller’s job; split does not do it.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("tags").split(",")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

starts_with 

starts_with(bin, prefix[, context])
Description

Returns whether the string bin starts with prefix. Treats canonically equivalent text as equal.

Arguments
NameTypeDescription
binstring

Name of bin.

prefixstring

Prefix to test.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
boolean
Introduced
8.2.0
Expression form

string_starts_with

Examples
Test a prefix

Given email = "user@corp.io", calling starts_with("email", "user") returns true, and starts_with("email", "corp") returns false.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").startsWith("user")
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

strlen 

strlen(bin[, context])
Description

Returns the number of Unicode codepoints in the string bin.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
integer
Introduced
8.2.0
Expression form

string_strlen

Examples
Count codepoints

Given email = "aná@corp.io", calling strlen("email") returns 11, while byte_length returns 12. The accented character is one codepoint and two UTF-8 bytes.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").strlen()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

substr 

substr(bin, from[, to][, context])
Description

Returns a substring by codepoint index. from is inclusive; to is exclusive. Supports negative indexes.

Arguments
NameTypeDescription
binstring

Name of bin.

frominteger

Start codepoint index (inclusive).

tointeger

End codepoint index (exclusive). Optional, and defaults to the string’s codepoint length, returning the substring from from to the end of the string. Clients expose the two-argument form as substr and the three-argument form as substr_range in Python and C, and as an overload of substr in Java.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
string
Introduced
8.2.0
Expression form

string_substr

Examples
Extract a codepoint range

Given email = "ana@corp.io", calling substr("email", 0, 3) returns "ana". The range is half-open, so the codepoint at to is not included. Omitting to runs to the end of the string.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("email").substr(0, 3)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

to_blob 

to_blob(bin[, context])
Description

Returns the UTF-8 bytes of the string bin as a Blob.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
blob
Introduced
8.2.0
Expression form

string_to_blob

Examples
Reinterpret the value as bytes

Given payload = "hi", calling to_blob("payload") returns a 2-byte Blob holding the UTF-8 bytes of the string. The stored value is unchanged.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("payload").stringToBlob()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

to_double 

to_double(bin[, context])
Description

Parses the string bin as a float. Accepts decimal digits, exponent form, and the inf and nan literals.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
float
Introduced
8.2.0
Expression form

string_to_double

Examples
Parse the value as a float

Given rate = "1.5", calling to_double("rate") returns 1.5. Exponent form such as 1.5e10 parses too.

Accepted grammar

An optional sign followed by decimal digits, with an optional fractional part and an optional exponent: -1.5, 1.5e10, 2E-3. The case-insensitive literals inf, infinity, and nan are accepted, with an optional sign, so every value to_string emits for a float parses back.

Those three succeed and return a non-finite float rather than an error, so a bin holding the word nan converts rather than failing. Summing or averaging to_double over a text column poisons the whole aggregate from one such row. Filter the rows or check each value before aggregating.

These forms are rejected, though some languages’ own float parsers accept them: leading whitespace (" 42"), hexadecimal (0x10, 0x1p3), a . with no digit after it (5., 5.e3), and nan payloads (nan(0x1)). Trailing characters are rejected too, so 12abc does not parse as 12.

Parse failures

A string that is not a valid float, or whose value does not fit in double, returns AS_ERR_OP_NOT_APPLICABLE with subcode AS_SUB_OPNOT_STRING_CONVERSION_FAILED. It does not return AS_ERR_PARAMETER, which is reserved for a malformed operation rather than unparseable data. Branch on AS_ERR_OP_NOT_APPLICABLE to catch failed conversions.

to_double accepts exponent form such as 1e5, and the inf and nan literals, all of which is_numeric rejects, so is_numeric is not a valid guard for this operation.

A string longer than 327 characters is rejected on length alone, before any parsing. That is the longest decimal form a double can take, which the smallest values need when written out in full.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("rate").stringToDouble()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

to_integer 

to_integer(bin[, context])
Description

Parses the string bin as a signed integer.

Arguments
NameTypeDescription
binstring

Name of bin.

contextContext instance

Optional context path from the bin to a string nested inside a List or Map, one selector per nesting level. Omit it when the bin holds the string itself.

Returns
integer
Introduced
8.2.0
Expression form

string_to_integer

Examples
Parse the value as an integer

Given count = "42", calling to_integer("count") returns 42. A value that does not parse, or does not fit in int64, returns an error rather than a partial result.

Parse failures

A string that is not a valid integer, or whose value does not fit in int64, returns AS_ERR_OP_NOT_APPLICABLE with subcode AS_SUB_OPNOT_STRING_CONVERSION_FAILED. It does not return AS_ERR_PARAMETER, which is reserved for a malformed operation rather than unparseable data. Branch on AS_ERR_OP_NOT_APPLICABLE to catch failed conversions.

A string longer than 20 characters is rejected on length alone, before any parsing. Twenty characters is the longest valid int64, -9223372036854775808, so nothing longer can be in range.

Code sample 
try (RecordStream rs = session.query(key)
    .bin("count").stringToInteger()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}

Type conversion

to_string 

to_string(bin)
Description

Converts an integer, float, boolean, blob, or string bin to its string representation.

Arguments
NameTypeDescription
binstring

Name of bin.

Returns
string
Introduced
8.2.0
Expression form

to_string

Examples
Convert a bin without knowing its type

A record stores a counter in a bin called score, and the caller does not know the bin’s type in advance. Given score = 42, calling to_string("score") returns "42".

Result by source type
Bin typeResult
IntegerExact decimal.
FloatSix significant digits, in exponent form outside [1e-5, 1e6). 3.141592653589793 becomes "3.14159", and 1234567.0 becomes "1.23457e+06".
Boolean"true" or "false".
BlobThe stored bytes as they are, not base64 or hex. A blob holding invalid UTF-8 returns AS_ERR_OP_NOT_APPLICABLE.
StringUnchanged.
Conversions that lose data or fail

Float is the one supported type that loses information. to_string followed by to_double does not round-trip a float: 1234567.0 returns as 1234570.0. Convert on the client when the exact value matters.

List, Map, GeoJSON, and HLL bins are not supported at all and return AS_ERR_INCOMPATIBLE_TYPE.

Code sample 
try (RecordStream rs = session.query(key)
    .appendOperations(StringOperation.toString("score"))
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}