Skip to content

String

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Overview

A String bin holds one sequence of UTF-8 text. String operations (Database 8.2.0 and later) read, transform, and convert that value directly on the Aerospike server, so an application can search, slice, normalize, and reformat text without fetching the record to the client.

String is a scalar data type: a single value with nothing nested inside it. A String can itself be stored inside a List or Map, and string operations reach it there through a nested context path.

Two surfaces run the same string logic. String operations act in place on a bin through the operate command. String expressions evaluate to a value, which you can filter on, return from a projection, or store. For the distinction in general and which to reach for, see Operations and expressions.

Two things about that split are specific to String:

  • String modify operations return no value. To see what a modify produced, add a read operation for the same bin to the same command.
  • Invalid UTF-8 surfaces differently on each. Through operate a malformed bin returns AS_ERR_INVALID_ENCODING; in a filter expression it evaluates to unknown and the record is silently excluded from results. See String operations and UTF-8 validation.

To see a first command on either surface, see the 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.