.. _collation_dialog:

*************************
`Collation Dialog`:index:
*************************

Use the *Collation* dialog to define a collation. A collation is an SQL schema
object that maps a SQL name to operating system locales. To create a collation,
you must have a CREATE privilege on the destination schema.

The *Collation* dialog organizes the development of a collation through the
following dialog tabs: *General* and *Definition*. The *SQL* tab displays the
SQL code generated by dialog selections.

.. image:: images/collation_general.png
    :alt: Collation dialog general tab
    :align: center

Use the fields in the *General* tab to identify the collation:

* Use the *Name* field to provide a name for the collation. The collation name
  must be unique within a schema. The name will be displayed in the *pgAdmin*
  tree control.
* Select the name of the owner from the drop-down listbox in the *Owner* field.
* Select the name of the schema in which the collation will reside from the
  drop-down listbox in the *Schema* field.
* Store notes about the collation in the *Comment* field.

Click the *Definition* tab to continue.

.. image:: images/collation_definition.png
    :alt: Collation dialog definition tab
    :align: center

Use the fields in the *Definition* tab to specify the operating system locale
settings:

* Use the drop-down listbox next to *Copy collation* to select the name of an
  existing collation to copy. The new collation will have the same properties
  as the existing one, but will be an independent object. If you choose to copy
  an existing collation, you cannot modify the collation properties displayed on
  this tab.
* Use the *Locale* field to specify a locale; a locale specifies language and
  language formatting characteristics. If you specify this, you cannot specify
  either of the following parameters. To view a list of locales supported by
  your Linux system use the command *locale -a*.
* Use the *LC_COLLATE* field to specify a locale with specified string sort
  order. The locale must be applicable to the current database encoding. (See
  CREATE DATABASE for details.)
* Use the *LC_CTYPE* field to specify a locale with specified character
  classification. The locale must be applicable to the current database encoding.
  (See CREATE DATABASE for details.)
* Use the drop-down listbox next to *Locale Provider* to select a locale services associated
  with the collation. Possible values are: icu, libc. libc is the default.
* Move the switch next to *Deterministic* to *YES* to specify whether the collation should use
  deterministic comparisons. By default, this option is set to true. In a
  deterministic comparison, strings that are not byte-wise equal are considered
  unequal, even if they are considered logically equal in the comparison.
* Use the *Rules* field to specify a rules for customizing the behavior of the collation.
  It includes considerations such as character ordering, case sensitivity, and accent
  sensitivity.
* Use the *Version* field to specify version string to store with the collation object.


Click the *SQL* tab to continue.

Your entries in the *Collation* dialog generate a SQL command (see an example b
elow). Use the *SQL* tab for review; revisit or switch tabs to make any changes
to the SQL command.

Example
*******

The following is an example of the sql command generated by user selections in
the *Collation* dialog:

.. image:: images/collation_sql.png
    :alt: Collation dialog sql tab
    :align: center

The example shown demonstrates creating a collation named *french* that uses the
rules specified for the locale, *fr-BI-x-icu.  The collation is owned by
*postgres*.

* Click the *Info* button (i) to access online help. For more information about
  setting a locale, see Chapter 22.1 Locale Support of the PostgreSQL core
  documentation:

   https://www.postgresql.org/docs/current/locale.html

* Click the *Save* button to save work.
* Click the *Close* button to exit without saving work.
* Click the *Reset* button to restore configuration parameters.