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#