Skip to main content
`Ctrl`+`K`

# 7.16.30. `string_truncate`

Added in version 16.0.9.

## 7.16.30.1. Summary

`string_truncate` truncates a string to at most the specified number of characters. If the string is truncated, the tail of the kept characters is replaced with an omission mark so that the result, including the omission mark, is `length` characters long, in the same way as Ruby on Rails’ `String#truncate`.

To enable this function, register `functions/string` plugin with the following command:

    plugin_register functions/string

## 7.16.30.2. Syntax

`string_truncate` requires two or three parameters.

    string_truncate(target, length[, options])

`options` uses the following format. All key-value pairs are optional:

    {
      "omission": omission
    }

## 7.16.30.3. Usage

Here are a schema definition and sample data to show usage.

Sample schema:

Execution example:

    plugin_register functions/string
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Memos TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]

Sample data:

Execution example:

    load --table Memos
    [
    {"_key": "Groonga is a full text search engine"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

Here is a simple example. Because the string is longer than the specified `length`, it’s truncated and `"..."` is appended so that the result is 15 characters long.

Execution example:

    select Memos \
      --output_columns '_key, string_truncate(_key, 15)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a..."
    #       ]
    #     ]
    #   ]
    # ]

If the string isn’t longer than `length`, it’s returned as-is without an omission mark.

Execution example:

    select Memos \
      --output_columns '_key, string_truncate(_key, 100)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a full text search engine"
    #       ]
    #     ]
    #   ]
    # ]

The following example specifies a custom `omission` in `options`.

Execution example:

    select Memos \
      --output_columns '_key, string_truncate(_key, 15, { "omission" : "＊＊＊" })'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a＊＊＊"
    #       ]
    #     ]
    #   ]
    # ]

When truncation occurs and `length` is smaller than the number of characters in `omission`, the result is only `omission` even if `omission` is longer than `length`.

Execution example:

    select Memos \
      --output_columns '_key, string_truncate(_key, 2)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "..."
    #       ]
    #     ]
    #   ]
    # ]

You can specify a string literal instead of a column.

Execution example:

    select Memos \
      --output_columns 'string_truncate("Groonga is a fast fulltext search engine", 15)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a..."
    #       ]
    #     ]
    #   ]
    # ]

## 7.16.30.4. Parameters

### 7.16.30.4.1. Required parameters

#### 7.16.30.4.1.1. `target`

Specify a string literal or a string type column.

#### 7.16.30.4.1.2. `length`

Specify the maximum number of characters of the result, including the `omission` mark when truncation occurs. If the number of characters in `target` is less than or equal to `length`, `target` is returned as-is.

If `target` is longer than `length`, `string_truncate` subtracts the number of characters in `omission` from `length`, extracts that many characters from the beginning of `target`, and appends `omission`. If `omission` is longer than `length` or `length` is negative, the result is `omission`.

### 7.16.30.4.2. Optional parameters

#### 7.16.30.4.2.1. `options`

Specify the following key.

- `omission`

  - Specify a string to be appended to the truncated string to show that it was truncated.

  - The default is `"..."`.

## 7.16.30.5. Return value

`string_truncate` returns `target` truncated. When truncation occurs, the result (kept part + `omission`) is `length` characters long unless `omission` is longer than `length` or `length` is negative, in which case the result is `omission`.

## 7.16.30.6. See also

- snippet

- string_substring