begriffs open source - ai-pg/blob - full-docs/txt/sql-createcollation.txt

   1
   2 CREATE COLLATION
   3
   4    CREATE COLLATION — define a new collation
   5
   6 Synopsis
   7
   8 CREATE COLLATION [ IF NOT EXISTS ] name (
   9     [ LOCALE = locale, ]
  10     [ LC_COLLATE = lc_collate, ]
  11     [ LC_CTYPE = lc_ctype, ]
  12     [ PROVIDER = provider, ]
  13     [ DETERMINISTIC = boolean, ]
  14     [ RULES = rules, ]
  15     [ VERSION = version ]
  16 )
  17 CREATE COLLATION [ IF NOT EXISTS ] name FROM existing_collation
  18
  19 Description
  20
  21    CREATE COLLATION defines a new collation using the specified operating
  22    system locale settings, or by copying an existing collation.
  23
  24    To be able to create a collation, you must have CREATE privilege on the
  25    destination schema.
  26
  27 Parameters
  28
  29    IF NOT EXISTS
  30           Do not throw an error if a collation with the same name already
  31           exists. A notice is issued in this case. Note that there is no
  32           guarantee that the existing collation is anything like the one
  33           that would have been created.
  34
  35    name
  36           The name of the collation. The collation name can be
  37           schema-qualified. If it is not, the collation is defined in the
  38           current schema. The collation name must be unique within that
  39           schema. (The system catalogs can contain collations with the
  40           same name for other encodings, but these are ignored if the
  41           database encoding does not match.)
  42
  43    locale
  44           The locale name for this collation. See Section 23.2.2.3.1 and
  45           Section 23.2.2.3.2 for details.
  46
  47           If provider is libc, this is a shortcut for setting LC_COLLATE
  48           and LC_CTYPE at once. If you specify locale, you cannot specify
  49           either of those parameters.
  50
  51           If provider is builtin, then locale must be specified and set to
  52           either C, C.UTF-8 or PG_UNICODE_FAST.
  53
  54    lc_collate
  55           If provider is libc, use the specified operating system locale
  56           for the LC_COLLATE locale category.
  57
  58    lc_ctype
  59           If provider is libc, use the specified operating system locale
  60           for the LC_CTYPE locale category.
  61
  62    provider
  63           Specifies the provider to use for locale services associated
  64           with this collation. Possible values are builtin, icu (if the
  65           server was built with ICU support) or libc. libc is the default.
  66           See Section 23.1.4 for details.
  67
  68    DETERMINISTIC
  69           Specifies whether the collation should use deterministic
  70           comparisons. The default is true. A deterministic comparison
  71           considers strings that are not byte-wise equal to be unequal
  72           even if they are considered logically equal by the comparison.
  73           PostgreSQL breaks ties using a byte-wise comparison. Comparison
  74           that is not deterministic can make the collation be, say, case-
  75           or accent-insensitive. For that, you need to choose an
  76           appropriate LOCALE setting and set the collation to not
  77           deterministic here.
  78
  79           Nondeterministic collations are only supported with the ICU
  80           provider.
  81
  82    rules
  83           Specifies additional collation rules to customize the behavior
  84           of the collation. This is supported for ICU only. See
  85           Section 23.2.3.4 for details.
  86
  87    version
  88           Specifies the version string to store with the collation.
  89           Normally, this should be omitted, which will cause the version
  90           to be computed from the actual version of the collation as
  91           provided by the operating system. This option is intended to be
  92           used by pg_upgrade for copying the version from an existing
  93           installation.
  94
  95           See also ALTER COLLATION for how to handle collation version
  96           mismatches.
  97
  98    existing_collation
  99           The name of an existing collation to copy. The new collation
 100           will have the same properties as the existing one, but it will
 101           be an independent object.
 102
 103 Notes
 104
 105    CREATE COLLATION takes a SHARE ROW EXCLUSIVE lock, which is
 106    self-conflicting, on the pg_collation system catalog, so only one
 107    CREATE COLLATION command can run at a time.
 108
 109    Use DROP COLLATION to remove user-defined collations.
 110
 111    See Section 23.2.2.3 for more information on how to create collations.
 112
 113    When using the libc collation provider, the locale must be applicable
 114    to the current database encoding. See CREATE DATABASE for the precise
 115    rules.
 116
 117 Examples
 118
 119    To create a collation from the operating system locale fr_FR.utf8
 120    (assuming the current database encoding is UTF8):
 121 CREATE COLLATION french (locale = 'fr_FR.utf8');
 122
 123    To create a collation using the ICU provider using German phone book
 124    sort order:
 125 CREATE COLLATION german_phonebook (provider = icu, locale = 'de-u-co-phonebk');
 126
 127    To create a collation using the ICU provider, based on the root ICU
 128    locale, with custom rules:
 129 CREATE COLLATION custom (provider = icu, locale = 'und', rules = '&V << w <<< W'
 130 );
 131
 132    See Section 23.2.3.4 for further details and examples on the rules
 133    syntax.
 134
 135    To create a collation from an existing collation:
 136 CREATE COLLATION german FROM "de_DE";
 137
 138    This can be convenient to be able to use operating-system-independent
 139    collation names in applications.
 140
 141 Compatibility
 142
 143    There is a CREATE COLLATION statement in the SQL standard, but it is
 144    limited to copying an existing collation. The syntax to create a new
 145    collation is a PostgreSQL extension.
 146
 147 See Also
 148
 149    ALTER COLLATION, DROP COLLATION