Text.ToBinary
TextEncodes a text value into binary using the specified character encoding.
Syntax
Text.ToBinary(text as text, optional encoding as nullable number) as binaryParameters
| Name | Type | Required | Description |
|---|---|---|---|
text | text | Yes | The text value to encode. |
encoding | number | No | A TextEncoding value specifying the character encoding. Defaults to TextEncoding.Utf8 (65001). Common values: TextEncoding.Ascii (20127), TextEncoding.Unicode (1200), TextEncoding.Utf8 (65001). |
Return Value
binary — A binary value containing the encoded text.
Remarks
Text.ToBinary encodes a text value into a binary value using the specified character encoding. This is the inverse of Text.FromBinary. The result is a binary type value — use it wherever binary data is required, such as when uploading to a web endpoint, storing in a binary column, or hashing with Binary.Buffer.
The encoding parameter accepts values from the TextEncoding enum:
- TextEncoding.Utf8 (65001) — default; correct for most APIs and modern files
- TextEncoding.Ascii (20127) — 7-bit ASCII; safe for codes and identifiers with no special characters
- TextEncoding.Unicode / TextEncoding.Utf16 (1200) — little-endian UTF-16
- TextEncoding.Utf16BE (1201) — big-endian UTF-16
- TextEncoding.Utf32 (12000)
- TextEncoding.Windows (1252) — legacy Windows Western European encoding
Always specify the encoding parameter explicitly. The default is TextEncoding.Utf8, which is correct for most modern scenarios, but making it explicit ensures the query behaves identically regardless of system locale. When the binary output will later be decoded by another system, ensure both sides use the same encoding — a mismatch will produce garbled output without raising an error.
Examples
Example 1: Encode a text value as UTF-8 binary
Text.ToBinary("Alice Smith", TextEncoding.Utf8)Result | |
|---|---|
| 1 | QWxpY2UgU21pdGg= |
Example 2: Encode with explicit UTF-8 for API payload preparation
Text.ToBinary("Widget A", TextEncoding.Utf8)Result | |
|---|---|
| 1 | V2lkZ2V0IEE= |
Example 3: Round-trip: encode then decode to verify correctness
let
original = "charlie smith",
encoded = Text.ToBinary(original, TextEncoding.Utf8),
decoded = Text.FromBinary(encoded, TextEncoding.Utf8)
in
decodedThe final output — decodes the binary back to text using Text.FromBinary, confirming the round-trip produces the original string.
Result | |
|---|---|
| 1 | charlie smith |