.. _version_3.2.0:

=============
Version 3.2.0
=============

Released on 2018/12/19.

.. NOTE::

    If you are upgrading a cluster, you must be running CrateDB 2.0.4 or higher
    before you upgrade to 3.2.0.

    We recommend that you upgrade to the latest 3.1 release before moving to
    3.2.0.

    You cannot perform a `rolling upgrade`_ to this version. Any upgrade to this
    version will require a `full restart upgrade`_.

    When restarting, CrateDB will migrate indexes to a newer format. Depending
    on the amount of data, this may delay node start-up time.

    Please consult the :ref:`version_3.0.0_upgrade_notes` before upgrading.

.. WARNING::

    Tables that were created prior to upgrading to CrateDB 2.x will not
    function with 3.2 and must be recreated before moving to 3.2.x.

    You can recreate tables using ``COPY TO`` and ``COPY FROM`` while running a
    2.x release into a new table, or by `inserting the data into a new table`_.

    Before upgrading, you should `back up your data`_.

.. _rolling upgrade: http://crate.io/docs/crate/guide/best_practices/rolling_upgrade.html
.. _full restart upgrade: http://crate.io/docs/crate/guide/best_practices/full_restart_upgrade.html
.. _back up your data: https://crate.io/a/backing-up-and-restoring-crate/
.. _inserting the data into a new table: https://crate.io/docs/crate/reference/en/latest/admin/system-information.html#tables-need-to-be-recreated


.. rubric:: Table of Contents

.. contents::
   :local:

.. _version_3.2.0_upgrade_notes:

Upgrade Notes
=============

Logging Configuration Changes
-----------------------------

The default logging configuration for CrateDB in ``log4j2.properties`` has been
changed. If you have customised this logging configuration, you should replace
the ``$marker`` entry with ``[%node_name] %marker``.

Deprecated Settings and Features
--------------------------------

In previous versions, the CrateDB license was set via the `license.ident`
configuration setting. This has now been deprecated, and going forward the
CrateDB license should be set using the :ref:`ref-set-license` statement.

The :ref:`ingest_mqtt` has been deprecated, and will be removed in the future.

The ``http.enabled`` setting has been deprecated, and will be removed in the
future.

The ``delimited_payload_filter`` built-in token filter for fulltext analyzers
has been renamed to ``delimited_payload``. The ``delimited_payload_filter`` name
can still be used, but is deprecated, and will be removed in the future.

Changelog
=========

Breaking Changes
----------------

- The ``*`` of ``SELECT *`` statements in the query clause of view definitions
  is no longer expanded at view creation time but lazy whenever a view is
  evaluated. That means columns added to a table after the views initial
  creation will show up in queries on the view. It is generally recommended to
  avoid using ``*`` in views but always specify columns explicitly.

Changes
-------

- ``geo_shape`` columns can now be casted to ``object`` with ``cast`` in
  addition to ``try_cast``.

- Added a ``ALTER CLUSTER GC DANGLING ARTIFACTS`` statement that can be used to
  clean up internal structures that weren't properly cleaned up due to cluster
  failures during operations which create such temporary artifacts.

- Added support for per-table shard allocation filtering.

- Added support for changing the number of shards on an existing table or
  partition using the ``ALTER TABLE SET`` statement.

- Improved resiliency of the ``ALTER TABLE RENAME`` operation by making it an
  atomic operation.

- Added support for executing aggregations as window functions using the
  ``OVER`` clause.

- Added an ``ALTER CLUSTER SWAP TABLE`` statement that can be used to switch the
  names of two tables.

- Functions like ``CURRENT_SCHEMA`` and ``CURRENT_USER`` which depend on the
  active session can now be used as generated columns.

- Added the ``REPLACE`` scalar function.

- Added the ``pg_catalog.pg_database`` table.

- Added support for ``SHOW parameter_name | ALL`` to retrieve one or all session
  setting value(s).

- Added support for ``INITCAP(string)`` and ``CURRENT_DATABASE`` scalar expressions.

- Improved the compatibility with postgres clients that use the ``text`` type
  for parameter encoding.

-  Upgraded the Admin UI to 1.11.3 which includes the following changes:

   - Changed the license information (ident) to be taken from the
     `sys.cluster.licence` attribute instead of the `license.ident` setting,
     which is ``@deprecated``.

   - Addition of French language files and menu options.

   - Fixed an issue that caused incorrectness in the navigation of the Admin UI.

   - Updated the license div to be responsive in the Admin UI.

   - Various Admin UI improvements.

- Changed PostgreSQL wire interface to emulate version ``10.5``.

-  Added support for CrateDB license management enabling users to trial the
   enterprise features, set a production enterprise license or continue
   using the community edition. Additionally, a new ``SET LICENSE`` statement
   has been added for license registration, and the ``license.ident`` setting
   has become ``@deprecated``.

- The ``MQTT`` endpoint has been deprecated and will be removed in a future
  version.

- Upgraded to Elasticsearch 6.5.1, which includes changes to the default logging
  configuration.

- Deprecated the ``http.enabled`` setting.

- Added a ``remove_duplicates`` token filter.

- Added a ``char_group`` tokenizer.

- Renamed the ``delimited_payload_filter`` token filter to
  ``delimited_payload``. The old name can still be used, but is deprecated.

- Added the ``GENERATE_SERIES(start, stop [, step ])`` table function.

- Added ``pg_class``, ``pg_namespace``, ``pg_attribute``, ``pg_attrdef``,
  ``pg_index`` and ``pg_constraint`` tables to the ``pg_catalog`` schema for
  improved compatibility with postgresql.

- Added support for using table functions in the select list of a query.

- Implemented the ``array_upper``, ``array_length`` and ``array_lower`` scalars
  that return the upper and respectively lower bound of a given array
  dimension.

- Added some type aliases for improved compatibility with postgresql.

- Expand the ``search_path`` setting to accept a list of schemas that will be
  searched when a relation (table, view or user defined function) is referenced
  without specifying a schema. The system ``pg_catalog`` schema is implicitly
  included as the first one in the path.

- Improved the handling of function expressions inside subscripts used on
  object columns. This allows expressions like ``obj['x' || 'x']`` to be used.

- The ``= ANY`` operator now also supports operations on object arrays or
  nested arrays. This enables queries like ``WHERE ['foo', 'bar'] =
  ANY(object_array(string_array))``.

- Added support for the ``ARRAY(subquery)`` expression.

- ``<object_column> = <object_literal>`` comparisons now try to utilize the
  index for the objects contents and can therefore run much faster.

- Values of byte-size and time based configuration setting do not require a unit
  suffix anymore. Without a unit time values are treat as milliseconds since
  epoch and byte size values are treat as bytes.

- Added support of using units inside byte-size or time bases statement
  parameters values. E.g. '1mb' for 1 MegaByte or '1s' for 1 Second.

