--- title: "String" description: "Guide to the Aerospike String data type, covering UTF-8 and ICU semantics, the two API surfaces, and the operation set." --- # String > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/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](https://aerospike.com/docs/develop/data-types/scalar): a single value with nothing nested inside it. A String can itself be stored inside a [List](https://aerospike.com/docs/develop/data-types/collections/list) or [Map](https://aerospike.com/docs/develop/data-types/collections/map), and string operations reach it there through a [nested context](https://aerospike.com/docs/develop/data-types/collections/context) path. Two surfaces run the same string logic. [String operations](https://aerospike.com/docs/develop/data-types/string/operations) act in place on a bin through the `operate` command. [String expressions](https://aerospike.com/docs/develop/expressions/string) 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](https://aerospike.com/docs/develop/learn/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](https://aerospike.com/docs/database/advanced/special-upgrades/820-upgrade#string-operations-and-utf-8-validation). To see a first command on either surface, see the [examples](https://aerospike.com/docs/develop/data-types/string/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](https://aerospike.com/docs/develop/data-types/string/comparison). - 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](https://aerospike.com/docs/database/advanced/special-upgrades/820-upgrade#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](https://aerospike.com/docs/develop/data-types/collections/context) path. Read commands return a value and leave the stored string unchanged, for example [`strlen`](https://aerospike.com/docs/develop/data-types/string/operations#strlen), [`substr`](https://aerospike.com/docs/develop/data-types/string/operations#substr), [`find`](https://aerospike.com/docs/develop/data-types/string/operations#find), [`contains`](https://aerospike.com/docs/develop/data-types/string/operations#contains), and [`split`](https://aerospike.com/docs/develop/data-types/string/operations#split). Modify commands transform the stored string in place, for example [`upper`](https://aerospike.com/docs/develop/data-types/string/operations#upper), [`trim`](https://aerospike.com/docs/develop/data-types/string/operations#trim), [`replace`](https://aerospike.com/docs/develop/data-types/string/operations#replace), [`regex_replace`](https://aerospike.com/docs/develop/data-types/string/operations#regex_replace), and [`insert`](https://aerospike.com/docs/develop/data-types/string/operations#insert). See [String operations](https://aerospike.com/docs/develop/data-types/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`](https://aerospike.com/docs/develop/data-types/string/operations#b64_decode) decodes a base64 String bin into a Blob. The encode direction, [`b64_encode`](https://aerospike.com/docs/develop/data-types/blob#b64_encode), is a [Blob/bytes](https://aerospike.com/docs/develop/data-types/blob) command. - To combine a list of strings into one value, use the List [`join`](https://aerospike.com/docs/develop/data-types/collections/list/operations#join) command. - For arbitrary binary data, use [Blob/bytes](https://aerospike.com/docs/develop/data-types/blob) 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](https://aerospike.com/docs/develop/data-types/string/operations#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`](https://aerospike.com/docs/develop/data-types/string/operations#append), [`prepend`](https://aerospike.com/docs/develop/data-types/string/operations#prepend), and [`string_regex_compare`](https://aerospike.com/docs/develop/expressions/string#string_regex_compare). ## Related pages - [Compare String values](https://aerospike.com/docs/develop/data-types/string/comparison) - [String operations](https://aerospike.com/docs/develop/data-types/string/operations) - [Upgrade to Database 8.2.0 and later](https://aerospike.com/docs/database/advanced/special-upgrades/820-upgrade#string-operations-and-utf-8-validation)