CREATE COLLATION

<< DDL statements | FB 2.1 Language Reference | DROP COLLATION >>

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
NameValuesValid forComment
DISABLE-COMPRESSIONS0, 11 bpcDisables 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-EXPANSIONS0, 11 bpcDisables expansions. Expansions cause certain characters (e.g. ligatures or umlauted vowels) to be treated as character sequences and sorted accordingly.
ICU-VERSIONdefault or M.mUNISpecifies 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).
LOCALExx_YYUNISpecifies the collation locale. Requires complete version of ICU libraries. Format: a locale string like du_NL (unquoted).
MULTI-LEVEL0, 11 bpcUses more than one ordering level.
SPECIALS-FIRST0, 11 bpcOrders 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.

See also:
Collate
Collation
DROP COLLATION
Firebird 2.1 Release Notes: International language support (INTL)

back to top of page
<< DDL statements | FB 2.1 Language Reference | DROP COLLATION >>