Skip to content

String

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike String bins hold UTF-8 encoded text as a scalar data type, a single value with nothing nested inside it. In Database 8.2.0 and later, you can inspect, transform, and reformat String values on the server, removing the client-side fetch-modify-write round trip.

You can also nest nest String values inside List or Map structures and manipulate them directly using a nested context path.

Operations vs. expressions

String capabilities are exposed through two distinct surfaces (for general guidance, see Operations and expressions):

  • String operations act in place on a bin using the operate command. Use this surface to update records on the server.

  • String expressions evaluate dynamically to a value. Use this surface for filtering queries, generating projections, or computing values.

Behavior specific to String

Two behaviors are specific to String:

  • Modify operations return no value. To inspect the result of a mutation, append a read operation for the same bin within the same operate command batch.
  • Invalid UTF-8 is handled differently on each surface:
    • In String operations, invalid UTF-8 returns AS_ERR_INVALID_ENCODING. A String expression in an operate projection returns AS_ERR_OP_NOT_APPLICABLE.
    • In filter expressions, invalid UTF-8 evaluates to unknown, silently excluding the record from query results. See String operations and UTF-8 validation.

For sample code, see String operation examples.

Unicode semantics

String operations treat a bin value as UTF-8 text rather than as bytes:

  • Length and index positions are counted in Unicode codepoints, not bytes.
  • Substring matching in find, contains, starts_with, ends_with, replace, and replace_all uses canonical equivalence, so a precomposed é (U+00E9) matches an e followed by a combining acute accent (U+0301).
  • Expression comparison operators (eq, ne, gt, ge, lt, le) order String values by UTF-8 bytes and do not treat those spellings as equal. See Compare String values.
  • Regular expressions use ICU syntax.
  • Case conversion and whitespace trimming follow Unicode character properties rather than ASCII ranges.

Operations require valid UTF-8 both in the stored value and in their arguments. For encoding errors and the repair path, see String operations and UTF-8 validation.

String API

Using the Aerospike client API, an application can read a whole String bin or operate on part of it. Commands work on a top-level bin, and on a String nested in a collection with an additional nested context path.

Read commands return a value and leave the stored string unchanged, for example strlen, substr, find, contains, and split.

Modify commands transform the stored string in place, for example upper, trim, replace, regex_replace, and insert.

See String operations for the full set, write flags, return types, error codes, and context.

Development guidelines and tips

  • Multiple commands on String, List, Map, and other scalar data types can be combined into a single-record command.
  • A String bin is created when a string value is written to it, or by a string modify command that creates a missing bin.
  • Running a transform on the server removes a fetch-modify-write round trip and keeps behavior consistent across client languages.
  • To convert between text and binary, b64_decode decodes a base64 String bin into a Blob. The encode direction, b64_encode, is a Blob/bytes command.
  • To combine a list of strings into one value, use the List join command.
  • For arbitrary binary data, use Blob/bytes bins rather than String.

Known limitations

  • A modify result is bound first by a per-operation result cap and then by the maximum record size. The two fail with different errors. See result size limits.
  • String commands operate on one bin in one record. They are not full-text search, an inverted index, or a cross-record join.
  • Legacy append and prepend, and the POSIX regexCompare expression, predate this API. Their replacements are append, prepend, and string_regex_compare.