meta data for this page
  •  

CREATE COLLATION

Available in: DSQL

Added in: 2.1

Description

Adds a collation to the database. The collation must already be present on your system (typically in a library file) and must be properly registered in a .conf file in the intl subdirectory of your Firebird installation. You may also base the collation on one that is already present in the database.

Syntax

CREATE COLLATION collname
  FOR charset
  [FROM basecoll | FROM EXTERNAL ('extname')]
  [NO PAD | PAD SPACE]
  [CASE [IN]SENSITIVE]
  [ACCENT [IN]SENSITIVE]
  ['<specific-attributes>']
collname              ::= the name to use for the new collation
charset               ::= a character set present in the database
basecoll              ::= a collation already present in the database
extname               ::= the collation name used in the .conf file
<specific-attributes> ::= <attribute> [; <attribute> ...]
<attribute>           ::= attrname=attrvalue
  • If no FROM clause is present, Firebird will scan the .conf file(s) in your intl subdirectory for a collation with the name specified after CREATE COLLATION. That is, omitting the FROM clause is the same as specifying FROM EXTERNAL ('collname').
  • The single-quoted extname is case-sensitive and must be exactly equal to the collation name in the .conf file. The collname, charset and basecoll parameters are case-insensitive, unless surrounded by double-quotes.

Specific attributes: The table below lists the available specific attributes. Not all specific attributes apply to every collation, even if specifying them doesn't cause an error. Please note that specific attributes are case sensitive. In the table below, 1 bpc indicates that an attribute is valid for collations of character sets using 1 byte per character (so-called narrow character sets). UNI stands for “UNICODE and UNICODE_CI”.

Table 5.1. Specific collation attributes

Name Values Valid for Comment
DISABLE-COMPRESSIONS 0, 1 1 bpc Disables compressions (aka contractions). Compressions cause certain character sequences to be sorted as atomic units, e.g. Spanish c+h as a single character ch.
DISABLE-EXPANSIONS 0, 1 1 bpc Disables expansions. Expansions cause certain characters (e.g. ligatures or umlauted vowels) to be treated as character sequences and sorted accordingly.
ICU-VERSION default or M.m UNI Specifies the ICU library version to use. Valid values are the ones defined in the applicable <intl_module> element in intl/fbintl.conf. Format: either the string literal default or a major+minor version number like 3.0 (both unquoted).
LOCALE xx_YY UNI Specifies the collation locale. Requires complete version of ICU libraries. Format: a locale string like du_NL (unquoted).
MULTI-LEVEL 0, 1 1 bpc Uses more than one ordering level.
SPECIALS-FIRST 0, 1 1 bpc Orders special characters (spaces, symbols etc.) before alphanumeric characters.

Examples

Simplest form, using the name as found in the .conf file (case-insensitive):

create collation iso8859_1_unicode for iso8859_1

Using a custom name. Notice how the “external” name must now exactly match the name in the .conf file:

create collation lat_uni
  for iso8859_1
  from external ('ISO8859_1_UNICODE')

Based on a collation already present in the database:

create collation es_es_nopad_ci
  for iso8859_1
  from es_es
  no pad
  case insensitive

With a special attribute (case-sensitive!):

create collation es_es_ci_compr
  for iso8859_1
  from es_es
  case insensitive
  'DISABLE-COMPRESSIONS=0'

Tip: If you want to add a new character set with its default collation in your database, declare and run the stored procedure sp_register_character_set(name, max_bytes_per_character), found in misc/intl.sql under your Firebird installation directory. Please note: in order for this to work, the character set must be present on your system and registered in a .conf file in the intl subdirectory.