QA_SRS020_ClickHouse_Extended_Precision_Data_Types = Specification(
name='QA-SRS020 ClickHouse Extended Precision Data Types',
description=None,
author=None,
date=None,
status=None,
approved_by=None,
approved_date=None,
approved_version=None,
version=None,
group=None,
type=None,
link=None,
uid=None,
parent=None,
children=None,
headings=(
Heading(name='Revision History', level=1, num='1'),
Heading(name='Introduction', level=1, num='2'),
Heading(name='Terminology', level=1, num='3'),
Heading(name='Extended Precision Data Types', level=2, num='3.1'),
Heading(name='Requirements', level=1, num='4'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision', level=2, num='4.1'),
Heading(name='Conversion', level=2, num='4.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt128', level=3, num='4.2.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt128', level=3, num='4.2.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt256', level=3, num='4.2.3'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt256', level=3, num='4.2.4'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toDecimal256', level=3, num='4.2.5'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.FromMySQL', level=3, num='4.2.6'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.ToMySQL', level=3, num='4.2.7'),
Heading(name='Arithmetic', level=2, num='4.3'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Int.Supported', level=3, num='4.3.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.Supported', level=3, num='4.3.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.NotSupported', level=3, num='4.3.3'),
Heading(name='Arrays', level=2, num='4.4'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.Supported', level=3, num='4.4.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.NotSupported', level=3, num='4.4.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.Supported', level=3, num='4.4.3'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.NotSupported', level=3, num='4.4.4'),
Heading(name='Comparison', level=2, num='4.5'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Comparison', level=3, num='4.5.1'),
Heading(name='Logical Functions', level=2, num='4.6'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Logical', level=3, num='4.6.1'),
Heading(name='Mathematical Functions', level=2, num='4.7'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.Supported', level=3, num='4.7.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.NotSupported', level=3, num='4.7.2'),
Heading(name='Rounding Functions', level=2, num='4.8'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.Supported', level=3, num='4.8.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.NotSupported', level=3, num='4.8.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.Supported', level=3, num='4.8.3'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.NotSupported', level=3, num='4.8.4'),
Heading(name='Bit Functions', level=2, num='4.9'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.Supported', level=3, num='4.9.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.NotSupported', level=3, num='4.9.2'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Dec.NotSupported', level=3, num='4.9.3'),
Heading(name='Null Functions', level=2, num='4.10'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Null', level=3, num='4.10.1'),
Heading(name='Tuple Functions', level=2, num='4.11'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Tuple', level=3, num='4.11.1'),
Heading(name='Map Functions', level=2, num='4.12'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Map.Supported', level=3, num='4.12.1'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Map.NotSupported', level=3, num='4.12.2'),
Heading(name='Create', level=2, num='4.13'),
Heading(name='RQ.SRS-020.ClickHouse.Extended.Precision.Create.Table', level=3, num='4.13.1'),
Heading(name='References', level=1, num='5'),
),
requirements=(
RQ_SRS_020_ClickHouse_Extended_Precision,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_toInt128,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_toUInt128,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_toInt256,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_toUInt256,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_toDecimal256,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_FromMySQL,
RQ_SRS_020_ClickHouse_Extended_Precision_Conversion_ToMySQL,
RQ_SRS_020_ClickHouse_Extended_Precision_Arithmetic_Int_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arithmetic_Dec_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arithmetic_Dec_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arrays_Int_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arrays_Int_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arrays_Dec_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Arrays_Dec_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Comparison,
RQ_SRS_020_ClickHouse_Extended_Precision_Logical,
RQ_SRS_020_ClickHouse_Extended_Precision_Mathematical_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Mathematical_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Rounding_Int_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Rounding_Int_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Rounding_Dec_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Rounding_Dec_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Bit_Int_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Bit_Int_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Bit_Dec_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Null,
RQ_SRS_020_ClickHouse_Extended_Precision_Tuple,
RQ_SRS_020_ClickHouse_Extended_Precision_Map_Supported,
RQ_SRS_020_ClickHouse_Extended_Precision_Map_NotSupported,
RQ_SRS_020_ClickHouse_Extended_Precision_Create_Table,
),
content='''
# QA-SRS020 ClickHouse Extended Precision Data Types
# Software Requirements Specification
## Table of Contents
* 1 [Revision History](#revision-history)
* 2 [Introduction](#introduction)
* 3 [Terminology](#terminology)
* 3.1 [Extended Precision Data Types](#extended-precision-data-types)
* 4 [Requirements](#requirements)
* 4.1 [RQ.SRS-020.ClickHouse.Extended.Precision](#rqsrs-020clickhouseextendedprecision)
* 4.2 [Conversion](#conversion)
* 4.2.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt128](#rqsrs-020clickhouseextendedprecisionconversiontoint128)
* 4.2.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt128](#rqsrs-020clickhouseextendedprecisionconversiontouint128)
* 4.2.3 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt256](#rqsrs-020clickhouseextendedprecisionconversiontoint256)
* 4.2.4 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt256](#rqsrs-020clickhouseextendedprecisionconversiontouint256)
* 4.2.5 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toDecimal256](#rqsrs-020clickhouseextendedprecisionconversiontodecimal256)
* 4.2.6 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.FromMySQL](#rqsrs-020clickhouseextendedprecisionconversionfrommysql)
* 4.2.7 [RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.ToMySQL](#rqsrs-020clickhouseextendedprecisionconversiontomysql)
* 4.3 [Arithmetic](#arithmetic)
* 4.3.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Int.Supported](#rqsrs-020clickhouseextendedprecisionarithmeticintsupported)
* 4.3.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.Supported](#rqsrs-020clickhouseextendedprecisionarithmeticdecsupported)
* 4.3.3 [RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.NotSupported](#rqsrs-020clickhouseextendedprecisionarithmeticdecnotsupported)
* 4.4 [Arrays](#arrays)
* 4.4.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.Supported](#rqsrs-020clickhouseextendedprecisionarraysintsupported)
* 4.4.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.NotSupported](#rqsrs-020clickhouseextendedprecisionarraysintnotsupported)
* 4.4.3 [RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.Supported](#rqsrs-020clickhouseextendedprecisionarraysdecsupported)
* 4.4.4 [RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.NotSupported](#rqsrs-020clickhouseextendedprecisionarraysdecnotsupported)
* 4.5 [Comparison](#comparison)
* 4.5.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Comparison](#rqsrs-020clickhouseextendedprecisioncomparison)
* 4.6 [Logical Functions](#logical-functions)
* 4.6.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Logical](#rqsrs-020clickhouseextendedprecisionlogical)
* 4.7 [Mathematical Functions](#mathematical-functions)
* 4.7.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.Supported](#rqsrs-020clickhouseextendedprecisionmathematicalsupported)
* 4.7.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.NotSupported](#rqsrs-020clickhouseextendedprecisionmathematicalnotsupported)
* 4.8 [Rounding Functions](#rounding-functions)
* 4.8.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.Supported](#rqsrs-020clickhouseextendedprecisionroundingintsupported)
* 4.8.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.NotSupported](#rqsrs-020clickhouseextendedprecisionroundingintnotsupported)
* 4.8.3 [RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.Supported](#rqsrs-020clickhouseextendedprecisionroundingdecsupported)
* 4.8.4 [RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.NotSupported](#rqsrs-020clickhouseextendedprecisionroundingdecnotsupported)
* 4.9 [Bit Functions](#bit-functions)
* 4.9.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.Supported](#rqsrs-020clickhouseextendedprecisionbitintsupported)
* 4.9.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.NotSupported](#rqsrs-020clickhouseextendedprecisionbitintnotsupported)
* 4.9.3 [RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Dec.NotSupported](#rqsrs-020clickhouseextendedprecisionbitdecnotsupported)
* 4.10 [Null Functions](#null-functions)
* 4.10.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Null](#rqsrs-020clickhouseextendedprecisionnull)
* 4.11 [Tuple Functions](#tuple-functions)
* 4.11.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Tuple](#rqsrs-020clickhouseextendedprecisiontuple)
* 4.12 [Map Functions](#map-functions)
* 4.12.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Map.Supported](#rqsrs-020clickhouseextendedprecisionmapsupported)
* 4.12.2 [RQ.SRS-020.ClickHouse.Extended.Precision.Map.NotSupported](#rqsrs-020clickhouseextendedprecisionmapnotsupported)
* 4.13 [Create](#create)
* 4.13.1 [RQ.SRS-020.ClickHouse.Extended.Precision.Create.Table](#rqsrs-020clickhouseextendedprecisioncreatetable)
* 5 [References](#references)
## Revision History
This document is stored in an electronic form using [Git] source control management software
hosted in a [GitHub Repository].
All the updates are tracked using the [Revision History].
## Introduction
This software requirements specification covers requirements related to [ClickHouse]
using extended precision data types.
## Terminology
### Extended Precision Data Types
Inclusive bounds:
* Int128 - [-170141183460469231731687303715884105728 : 170141183460469231731687303715884105727]
* UInt128 - [0 : 340282366920938463463374607431768211455]
* Int256 - [-57896044618658097711785492504343953926634992332820282019728792003956564819968 : 57896044618658097711785492504343953926634992332820282019728792003956564819967]
* UInt256 - [0 : 115792089237316195423570985008687907853269984665640564039457584007913129639935]
Exclusive bounds:
* Decimal256 - (10^(76 - S): 10^(76 - S)), where S is the scale.
## Requirements
### RQ.SRS-020.ClickHouse.Extended.Precision
version: 1.0
[ClickHouse] SHALL support using [Extended Precision Data Types].
### Conversion
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt128
version: 1.0
[ClickHouse] SHALL support converting values to `Int128` using the `toInt128` function.
For example,
```sql
SELECT toInt128(1)
```
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt128
version: 1.0
[ClickHouse] SHALL support converting values to `UInt128` format using `toUInt128` function.
For example,
```sql
SELECT toUInt128(1)
```
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toInt256
version: 1.0
[ClickHouse] SHALL support converting values to `Int256` using `toInt256` function.
For example,
```sql
SELECT toInt256(1)
```
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toUInt256
version: 1.0
[ClickHouse] SHALL support converting values to `UInt256` format using `toUInt256` function.
For example,
```sql
SELECT toUInt256(1)
```
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.toDecimal256
version: 1.0
[ClickHouse] SHALL support converting values to `Decimal256` format using `toDecimal256` function.
For example,
```sql
SELECT toDecimal256(1,2)
```
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.FromMySQL
version: 1.0
[ClickHouse] SHALL support converting to [Extended Precision Data Types] from MySQL.
#### RQ.SRS-020.ClickHouse.Extended.Precision.Conversion.ToMySQL
version: 1.0
[ClickHouse] MAY not support converting from [Extended Precision Data Types] to MySQL.
### Arithmetic
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Int.Supported
version: 1.0
[ClickHouse] SHALL support using [Arithmetic functions] with Int128, UInt128, Int256, and UInt256.
Arithmetic functions:
* plus
* minus
* multiply
* divide
* intDiv
* intDivOrZero
* modulo
* moduloOrZero
* negate
* abs
* gcd
* lcm
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Arithmetic functions] with Decimal256:
* plus
* minus
* multiply
* divide
* intDiv
* intDivOrZero
* negate
* abs
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arithmetic.Dec.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Arithmetic functions] with Decimal256:
* modulo
* moduloOrZero
* gcd
* lcm
### Arrays
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Array functions] with Int128, UInt128, Int256, and UInt256.
* empty
* notEmpty
* length
* arrayCount
* arrayPopBack
* arrayPopFront
* arraySort
* arrayReverseSort
* arrayUniq
* arrayJoin
* arrayDistinct
* arrayEnumerate
* arrayEnumerateDense
* arrayEnumerateUniq
* arrayReverse
* reverse
* arrayFlatten
* arrayCompact
* arrayExists
* arrayAll
* arrayMin
* arrayMax
* arraySum
* arrayAvg
* arrayReduce
* arrayReduceInRanges
* arrayZip
* arrayMap
* arrayFilter
* arrayFill
* arrayReverseFill
* arraySplit
* arrayFirst
* arrayFirstIndex
* arrayConcat
* hasAll
* hasAny
* hasSubstr
* arrayElement
* has
* indexOf
* countEqual
* arrayPushBack
* arrayPushFront
* arrayResize
* arraySlice
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Int.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Array functions] with Int128, UInt128, Int256, and UInt256:
* arrayDifference
* arrayCumSum
* arrayCumSumNonNegative
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Array functions] with Decimal256:
* empty
* notEmpty
* length
* arrayCount
* arrayPopBack
* arrayPopFront
* arraySort
* arrayReverseSort
* arrayUniq
* arrayJoin
* arrayDistinct
* arrayEnumerate
* arrayEnumerateDense
* arrayEnumerateUniq
* arrayReverse
* reverse
* arrayFlatten
* arrayCompact
* arrayExists
* arrayAll
* arrayReduce
* arrayReduceInRanges
* arrayZip
* arrayMap
* arrayFilter
* arrayFill
* arrayReverseFill
* arraySplit
* arrayFirst
* arrayFirstIndex
* arrayConcat
* hasAll
* hasAny
* hasSubstr
* arrayElement
* has
* indexOf
* countEqual
* arrayPushBack
* arrayPushFront
* arrayResize
* arraySlice
#### RQ.SRS-020.ClickHouse.Extended.Precision.Arrays.Dec.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Array functions] with Decimal256:
* arrayMin
* arrayMax
* arraaySum
* arrayAvg
* arrayDifference
* arrayCumSum
* arrayCumSumNonNegative
### Comparison
#### RQ.SRS-020.ClickHouse.Extended.Precision.Comparison
version: 1.0
[ClickHouse] SHALL support using [Comparison functions] with [Extended Precision Data Types].
Comparison functions:
* equals
* notEquals
* less
* greater
* lessOrEquals
* greaterOrEquals
### Logical Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Logical
version: 1.0
[ClickHouse] MAY not support using [Logical functions] with [Extended Precision Data Types].
Logical functions:
* and
* or
* not
* xor
### Mathematical Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Mathematical functions] with [Extended Precision Data Types]:
* exp
* log, ln
* exp2
* log2
* exp10
* log10
* sqrt
* cbrt
* erf
* erfc
* lgamma
* tgamma
* sin
* cos
* tan
* asin
* acos
* atan
* cosh
* acosh
* sinh
* asinh
* tanh
* atanh
* log1p
* sign
#### RQ.SRS-020.ClickHouse.Extended.Precision.Mathematical.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Mathematical functions] with [Extended Precision Data Types]:
* pow, power
* intExp2
* intExp10
* atan2
* hypot
### Rounding Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Rounding functions] with Int128, UInt128, Int256, and UInt256:
* floor
* ceil
* trunc
* round
* roundBankers
* roundDuration
* roundAge
#### RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Int.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Rounding functions] with Int128, UInt128, Int256, and UInt256:
* roundDown
* roundToExp2
#### RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Rounding functions] with Decimal256:
* floor
* ceil
* trunc
* round
* roundBankers
#### RQ.SRS-020.ClickHouse.Extended.Precision.Rounding.Dec.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Rounding functions] with Decimal256:
* roundDuration
* roundAge
* roundDown
* roundToExp2
### Bit Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Bit functions] with Int128, UInt128, Int256, and UInt256:
* bitAnd
* bitOr
* bitXor
* bitNot
* bitShiftLeft
* bitShiftRight
* bitCount
#### RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Int.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Bit functions] with Int128, UInt128, Int256, and UInt256:
* bitRotateLeft
* bitRotateRight
* bitTest
* bitTestAll
* bitTestAny
#### RQ.SRS-020.ClickHouse.Extended.Precision.Bit.Dec.NotSupported
version: 1.0
[ClickHouse] MAY not support using [Bit functions] with Decimal256.
Bit functions:
* bitAnd
* bitOr
* bitXor
* bitNot
* bitShiftLeft
* bitShiftRight
* bitCount
* bitRotateLeft
* bitRotateRight
* bitTest
* bitTestAll
* bitTestAny
### Null Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Null
version: 1.0
[ClickHouse] SHALL support using [Null functions] with [Extended Precision Data Types].
Null functions:
* isNull
* isNotNull
* coalesce
* ifNull
* nullIf
* assumeNotNull
* toNullable
### Tuple Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Tuple
version: 1.0
[ClickHouse] SHALL support using [Tuple functions] with [Extended Precision Data Types].
Tuple functions:
* tuple
* tupleElement
* untuple
### Map Functions
#### RQ.SRS-020.ClickHouse.Extended.Precision.Map.Supported
version: 1.0
[ClickHouse] SHALL support using the following [Map functions] with [Extended Precision Data Types]:
* map
* mapContains
* mapKeys
* mapValues
#### RQ.SRS-020.ClickHouse.Extended.Precision.Map.NotSupported
version: 1.0
[ClickHouse] MAY not support using the following [Map functions] with [Extended Precision Data Types]:
* mapAdd
* mapSubtract
* mapPopulateSeries
### Create
#### RQ.SRS-020.ClickHouse.Extended.Precision.Create.Table
version: 1.0
[ClickHouse] SHALL support creating table with columns that use [Extended Precision Data Types].
## References
* **ClickHouse:** https://clickhouse.tech
* **GitHub Repository**: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/extended_precision_data_types/requirements/requirements.md
* **Revision History**: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/extended_precision_data_types/requirements/requirements.md
* **Git:** https://git-scm.com/
[Extended Precision Data Types]: #extended-precision-data-types
[Arithmetic functions]: https://clickhouse.tech/docs/en/sql-reference/functions/arithmetic-functions/
[Array functions]: https://clickhouse.tech/docs/en/sql-reference/functions/array-functions/
[Comparison functions]: https://clickhouse.tech/docs/en/sql-reference/functions/comparison-functions/
[Logical Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/logical-functions/
[Mathematical Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/math-functions/
[Rounding Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/rounding-functions/
[Bit Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/bit-functions/
[Null Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/functions-for-nulls/
[Tuple Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/tuple-functions/
[Map Functions]: https://clickhouse.tech/docs/en/sql-reference/functions/tuple-map-functions/
[SRS]: #srs
[ClickHouse]: https://clickhouse.tech
[GitHub Repository]: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/extended_precision_data_types/requirements/requirements.md
[Revision History]: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/extended_precision_data_types/requirements/requirements.md
[Git]: https://git-scm.com/
[GitHub]: https://github.com
''')
QA_SRS016_ClickHouse_Kerberos_Authentication = Specification(
name='QA-SRS016 ClickHouse Kerberos Authentication',
description=None,
author=None,
date=None,
status=None,
approved_by=None,
approved_date=None,
approved_version=None,
version=None,
group=None,
type=None,
link=None,
uid=None,
parent=None,
children=None,
headings=(
Heading(name='Revision History', level=1, num='1'),
Heading(name='Introduction', level=1, num='2'),
Heading(name='Terminology', level=1, num='3'),
Heading(name='Requirements', level=1, num='4'),
Heading(name='Generic', level=2, num='4.1'),
Heading(name='RQ.SRS-016.Kerberos', level=3, num='4.1.1'),
Heading(name='Ping', level=2, num='4.2'),
Heading(name='RQ.SRS-016.Kerberos.Ping', level=3, num='4.2.1'),
Heading(name='Configuration', level=2, num='4.3'),
Heading(name='RQ.SRS-016.Kerberos.Configuration.MultipleAuthMethods',
level=3,
num='4.3.1'),
Heading(name='RQ.SRS-016.Kerberos.Configuration.KerberosNotEnabled',
level=3,
num='4.3.2'),
Heading(
name='RQ.SRS-016.Kerberos.Configuration.MultipleKerberosSections',
level=3,
num='4.3.3'),
Heading(name='RQ.SRS-016.Kerberos.Configuration.WrongUserRealm',
level=3,
num='4.3.4'),
Heading(
name='RQ.SRS-016.Kerberos.Configuration.PrincipalAndRealmSpecified',
level=3,
num='4.3.5'),
Heading(
name='RQ.SRS-016.Kerberos.Configuration.MultiplePrincipalSections',
level=3,
num='4.3.6'),
Heading(name='RQ.SRS-016.Kerberos.Configuration.MultipleRealmSections',
level=3,
num='4.3.7'),
Heading(name='Valid User', level=2, num='4.4'),
Heading(name='RQ.SRS-016.Kerberos.ValidUser.XMLConfiguredUser',
level=3,
num='4.4.1'),
Heading(name='RQ.SRS-016.Kerberos.ValidUser.RBACConfiguredUser',
level=3,
num='4.4.2'),
Heading(name='RQ.SRS-016.Kerberos.ValidUser.KerberosNotConfigured',
level=3,
num='4.4.3'),
Heading(name='Invalid User', level=2, num='4.5'),
Heading(name='RQ.SRS-016.Kerberos.InvalidUser', level=3, num='4.5.1'),
Heading(name='RQ.SRS-016.Kerberos.InvalidUser.UserDeleted',
level=3,
num='4.5.2'),
Heading(name='Kerberos Not Available', level=2, num='4.6'),
Heading(
name='RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidServerTicket',
level=3,
num='4.6.1'),
Heading(
name='RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidClientTicket',
level=3,
num='4.6.2'),
Heading(name='RQ.SRS-016.Kerberos.KerberosNotAvailable.ValidTickets',
level=3,
num='4.6.3'),
Heading(name='Kerberos Restarted', level=2, num='4.7'),
Heading(name='RQ.SRS-016.Kerberos.KerberosServerRestarted',
level=3,
num='4.7.1'),
Heading(name='Performance', level=2, num='4.8'),
Heading(name='RQ.SRS-016.Kerberos.Performance', level=3, num='4.8.1'),
Heading(name='Parallel Requests processing', level=2, num='4.9'),
Heading(name='RQ.SRS-016.Kerberos.Parallel', level=3, num='4.9.1'),
Heading(
name=
'RQ.SRS-016.Kerberos.Parallel.ValidRequests.KerberosAndNonKerberos',
level=3,
num='4.9.2'),
Heading(
name='RQ.SRS-016.Kerberos.Parallel.ValidRequests.SameCredentials',
level=3,
num='4.9.3'),
Heading(
name=
'RQ.SRS-016.Kerberos.Parallel.ValidRequests.DifferentCredentials',
level=3,
num='4.9.4'),
Heading(name='RQ.SRS-016.Kerberos.Parallel.ValidInvalid',
level=3,
num='4.9.5'),
Heading(name='RQ.SRS-016.Kerberos.Parallel.Deletion',
level=3,
num='4.9.6'),
Heading(name='References', level=1, num='5'),
),
requirements=(
RQ_SRS_016_Kerberos,
RQ_SRS_016_Kerberos_Ping,
RQ_SRS_016_Kerberos_Configuration_MultipleAuthMethods,
RQ_SRS_016_Kerberos_Configuration_KerberosNotEnabled,
RQ_SRS_016_Kerberos_Configuration_MultipleKerberosSections,
RQ_SRS_016_Kerberos_Configuration_WrongUserRealm,
RQ_SRS_016_Kerberos_Configuration_PrincipalAndRealmSpecified,
RQ_SRS_016_Kerberos_Configuration_MultiplePrincipalSections,
RQ_SRS_016_Kerberos_Configuration_MultipleRealmSections,
RQ_SRS_016_Kerberos_ValidUser_XMLConfiguredUser,
RQ_SRS_016_Kerberos_ValidUser_RBACConfiguredUser,
RQ_SRS_016_Kerberos_ValidUser_KerberosNotConfigured,
RQ_SRS_016_Kerberos_InvalidUser,
RQ_SRS_016_Kerberos_InvalidUser_UserDeleted,
RQ_SRS_016_Kerberos_KerberosNotAvailable_InvalidServerTicket,
RQ_SRS_016_Kerberos_KerberosNotAvailable_InvalidClientTicket,
RQ_SRS_016_Kerberos_KerberosNotAvailable_ValidTickets,
RQ_SRS_016_Kerberos_KerberosServerRestarted,
RQ_SRS_016_Kerberos_Performance,
RQ_SRS_016_Kerberos_Parallel,
RQ_SRS_016_Kerberos_Parallel_ValidRequests_KerberosAndNonKerberos,
RQ_SRS_016_Kerberos_Parallel_ValidRequests_SameCredentials,
RQ_SRS_016_Kerberos_Parallel_ValidRequests_DifferentCredentials,
RQ_SRS_016_Kerberos_Parallel_ValidInvalid,
RQ_SRS_016_Kerberos_Parallel_Deletion,
),
content='''
# QA-SRS016 ClickHouse Kerberos Authentication
# Software Requirements Specification
## Table of Contents
* 1 [Revision History](#revision-history)
* 2 [Introduction](#introduction)
* 3 [Terminology](#terminology)
* 4 [Requirements](#requirements)
* 4.1 [Generic](#generic)
* 4.1.1 [RQ.SRS-016.Kerberos](#rqsrs-016kerberos)
* 4.2 [Ping](#ping)
* 4.2.1 [RQ.SRS-016.Kerberos.Ping](#rqsrs-016kerberosping)
* 4.3 [Configuration](#configuration)
* 4.3.1 [RQ.SRS-016.Kerberos.Configuration.MultipleAuthMethods](#rqsrs-016kerberosconfigurationmultipleauthmethods)
* 4.3.2 [RQ.SRS-016.Kerberos.Configuration.KerberosNotEnabled](#rqsrs-016kerberosconfigurationkerberosnotenabled)
* 4.3.3 [RQ.SRS-016.Kerberos.Configuration.MultipleKerberosSections](#rqsrs-016kerberosconfigurationmultiplekerberossections)
* 4.3.4 [RQ.SRS-016.Kerberos.Configuration.WrongUserRealm](#rqsrs-016kerberosconfigurationwronguserrealm)
* 4.3.5 [RQ.SRS-016.Kerberos.Configuration.PrincipalAndRealmSpecified](#rqsrs-016kerberosconfigurationprincipalandrealmspecified)
* 4.3.6 [RQ.SRS-016.Kerberos.Configuration.MultiplePrincipalSections](#rqsrs-016kerberosconfigurationmultipleprincipalsections)
* 4.3.7 [RQ.SRS-016.Kerberos.Configuration.MultipleRealmSections](#rqsrs-016kerberosconfigurationmultiplerealmsections)
* 4.4 [Valid User](#valid-user)
* 4.4.1 [RQ.SRS-016.Kerberos.ValidUser.XMLConfiguredUser](#rqsrs-016kerberosvaliduserxmlconfigureduser)
* 4.4.2 [RQ.SRS-016.Kerberos.ValidUser.RBACConfiguredUser](#rqsrs-016kerberosvaliduserrbacconfigureduser)
* 4.4.3 [RQ.SRS-016.Kerberos.ValidUser.KerberosNotConfigured](#rqsrs-016kerberosvaliduserkerberosnotconfigured)
* 4.5 [Invalid User](#invalid-user)
* 4.5.1 [RQ.SRS-016.Kerberos.InvalidUser](#rqsrs-016kerberosinvaliduser)
* 4.5.2 [RQ.SRS-016.Kerberos.InvalidUser.UserDeleted](#rqsrs-016kerberosinvaliduseruserdeleted)
* 4.6 [Kerberos Not Available](#kerberos-not-available)
* 4.6.1 [RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidServerTicket](#rqsrs-016kerberoskerberosnotavailableinvalidserverticket)
* 4.6.2 [RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidClientTicket](#rqsrs-016kerberoskerberosnotavailableinvalidclientticket)
* 4.6.3 [RQ.SRS-016.Kerberos.KerberosNotAvailable.ValidTickets](#rqsrs-016kerberoskerberosnotavailablevalidtickets)
* 4.7 [Kerberos Restarted](#kerberos-restarted)
* 4.7.1 [RQ.SRS-016.Kerberos.KerberosServerRestarted](#rqsrs-016kerberoskerberosserverrestarted)
* 4.8 [Performance](#performance)
* 4.8.1 [RQ.SRS-016.Kerberos.Performance](#rqsrs-016kerberosperformance)
* 4.9 [Parallel Requests processing](#parallel-requests-processing)
* 4.9.1 [RQ.SRS-016.Kerberos.Parallel](#rqsrs-016kerberosparallel)
* 4.9.2 [RQ.SRS-016.Kerberos.Parallel.ValidRequests.KerberosAndNonKerberos](#rqsrs-016kerberosparallelvalidrequestskerberosandnonkerberos)
* 4.9.3 [RQ.SRS-016.Kerberos.Parallel.ValidRequests.SameCredentials](#rqsrs-016kerberosparallelvalidrequestssamecredentials)
* 4.9.4 [RQ.SRS-016.Kerberos.Parallel.ValidRequests.DifferentCredentials](#rqsrs-016kerberosparallelvalidrequestsdifferentcredentials)
* 4.9.5 [RQ.SRS-016.Kerberos.Parallel.ValidInvalid](#rqsrs-016kerberosparallelvalidinvalid)
* 4.9.6 [RQ.SRS-016.Kerberos.Parallel.Deletion](#rqsrs-016kerberosparalleldeletion)
* 5 [References](#references)
## Revision History
This document is stored in an electronic form using [Git] source control management software
hosted in a [GitHub Repository].
All the updates are tracked using the [Git]'s [Revision History].
## Introduction
This document specifies the behavior for authenticating existing users via [Kerberos] authentication protocol.
Existing [ClickHouse] users, that are properly configured, have an ability to authenticate using [Kerberos]. Kerberos authentication is only supported for HTTP requests, and users configured to authenticate via Kerberos cannot be authenticated by any other means of authentication.
In order to use Kerberos authentication, Kerberos needs to be properly configured in the environment: Kerberos server must be present and user's and server's credentials must be set up. Configuring the Kerberos environment is outside the scope of this document.
## Terminology
* **Principal** -
A unique identity that uses [Kerberos].
* **Realm** -
A logical group of resources and identities that use [Kerberos].
* **Ticket** -
An encrypted block of data that authenticates principal.
* **Credentials** -
A Kerberos ticket and a session key.
* **Kerberized request** -
A HTTP query to ClickHouse server, which uses GSS [SPNEGO] and [Kerberos] to authenticate client.
* **Unkerberized request** -
A HTTP query to ClickHouse server, which uses any other mean of authentication than GSS [SPNEGO] or [Kerberos].
For a more detailed descriprion, visit [Kerberos terminology].
## Requirements
### Generic
#### RQ.SRS-016.Kerberos
version: 1.0
[ClickHouse] SHALL support user authentication using [Kerberos] server.
### Ping
#### RQ.SRS-016.Kerberos.Ping
version: 1.0
Docker containers SHALL be able to ping each other.
### Configuration
#### RQ.SRS-016.Kerberos.Configuration.MultipleAuthMethods
version: 1.0
[ClickHouse] SHALL generate an exception and TERMINATE in case some user in `users.xml` has a `<kerberos>` section specified alongside with any other authentication method's section, e.g. `ldap`, `password`.
#### RQ.SRS-016.Kerberos.Configuration.KerberosNotEnabled
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication in case user is properly configured for using Kerberos, but Kerberos itself is not enabled in `config.xml`. For example:
```xml
<clickhouse>
<!- ... -->
<kerberos />
</clickhouse>
```
```xml
<clickhouse>
<!- ... -->
<kerberos>
<principal>HTTP/[email protected]</principal>
</kerberos>
</clickhouse>
```
```xml
<clickhouse>
<!- ... -->
<kerberos>
<realm>EXAMPLE.COM</realm>
</kerberos>
</clickhouse>
```
#### RQ.SRS-016.Kerberos.Configuration.MultipleKerberosSections
version: 1.0
[ClickHouse] SHALL disable [Kerberos] and reject [Kerberos] authentication in case multiple `kerberos` sections are present in `config.xml`.
#### RQ.SRS-016.Kerberos.Configuration.WrongUserRealm
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if user's realm specified in `users.xml` doesn't match the realm of the principal trying to authenticate.
#### RQ.SRS-016.Kerberos.Configuration.PrincipalAndRealmSpecified
version: 1.0
[ClickHouse] SHALL generate an exception and disable [Kerberos] in case both `realm` and `principal` sections are defined in `config.xml`.
#### RQ.SRS-016.Kerberos.Configuration.MultiplePrincipalSections
version: 1.0
[ClickHouse] SHALL generate an exception and disable [Kerberos] in case multiple `principal` sections are specified inside `kerberos` section in `config.xml`.
#### RQ.SRS-016.Kerberos.Configuration.MultipleRealmSections
version: 1.0
[ClickHouse] SHALL generate an exception and disable [Kerberos] in case multiple `realm` sections are specified inside `kerberos` section in `config.xml`.
### Valid User
#### RQ.SRS-016.Kerberos.ValidUser.XMLConfiguredUser
version: 1.0
[ClickHouse] SHALL accept [Kerberos] authentication for a user that is configured in `users.xml` and has [Kerberos] enabled, i.e.:
```xml
<clickhouse>
<!- ... -->
<users>
<!- ... -->
<my_user>
<!- ... -->
<kerberos>
<realm>EXAMPLE.COM</realm>
</kerberos>
</my_user>
</users>
</clickhouse>
```
#### RQ.SRS-016.Kerberos.ValidUser.RBACConfiguredUser
version: 1.0
[ClickHouse] SHALL accept [Kerberos] authentication if user is configured to authenticate via [Kerberos] using SQL queries
```sql
CREATE USER my_user IDENTIFIED WITH kerberos REALM 'EXAMPLE.COM'
```
or
```sql
CREATE USER my_user IDENTIFIED WITH kerberos
```
#### RQ.SRS-016.Kerberos.ValidUser.KerberosNotConfigured
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if username is valid but [ClickHouse] user is not configured to be authenticated using [Kerberos].
### Invalid User
#### RQ.SRS-016.Kerberos.InvalidUser
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if name of the principal attempting to authenticate does not translate to a valid [ClickHouse] username configured in `users.xml` or via SQL workflow.
#### RQ.SRS-016.Kerberos.InvalidUser.UserDeleted
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if [ClickHouse] user was removed from the database using an SQL query.
### Kerberos Not Available
#### RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidServerTicket
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if [ClickHouse] user is configured to be authenticated using [Kerberos] and [Kerberos] server is unavailable, but [ClickHouse] doesn't have a valid Kerberos ticket or the ticket is expired.
#### RQ.SRS-016.Kerberos.KerberosNotAvailable.InvalidClientTicket
version: 1.0
[ClickHouse] SHALL reject [Kerberos] authentication if [ClickHouse] user is configured to to be authenticated using [Kerberos] and [Kerberos] server is unavailable, but the client doesn't have a valid Kerberos ticket or the ticket is expired.
#### RQ.SRS-016.Kerberos.KerberosNotAvailable.ValidTickets
version: 1.0
[ClickHouse] SHALL accept [Kerberos] authentication if no [Kerberos] server is reachable, but [ClickHouse] is configured to use valid credentials and [ClickHouse] has already processed some valid kerberized request (so it was granted a ticket), and the client has a valid ticket as well.
### Kerberos Restarted
#### RQ.SRS-016.Kerberos.KerberosServerRestarted
version: 1.0
[ClickHouse] SHALL accept [Kerberos] authentication if [Kerberos] server was restarted.
### Performance
#### RQ.SRS-016.Kerberos.Performance
version: 1.0
[ClickHouse]'s performance for [Kerberos] authentication SHALL be comparable to regular authentication.
### Parallel Requests processing
#### RQ.SRS-016.Kerberos.Parallel
version: 1.0
[ClickHouse] SHALL support parallel authentication using [Kerberos].
#### RQ.SRS-016.Kerberos.Parallel.ValidRequests.KerberosAndNonKerberos
version: 1.0
[ClickHouse] SHALL support processing of simultaneous kerberized (for users configured to authenticate via [Kerberos]) and non-kerberized (for users configured to authenticate with any other means) requests.
#### RQ.SRS-016.Kerberos.Parallel.ValidRequests.SameCredentials
version: 1.0
[ClickHouse] SHALL support processing of simultaneously sent [Kerberos] requests under the same credentials.
#### RQ.SRS-016.Kerberos.Parallel.ValidRequests.DifferentCredentials
version: 1.0
[ClickHouse] SHALL support processing of simultaneously sent [Kerberos] requests under different credentials.
#### RQ.SRS-016.Kerberos.Parallel.ValidInvalid
version: 1.0
[ClickHouse] SHALL support parallel authentication of users using [Kerberos] server, some of which are valid and some invalid. Valid users' authentication should not be affected by invalid users' attempts.
#### RQ.SRS-016.Kerberos.Parallel.Deletion
version: 1.0
[ClickHouse] SHALL not crash when two or more [Kerberos] users are simultaneously deleting one another.
## References
* **ClickHouse:** https://clickhouse.com
* **GitHub Repository:** https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/kerberos/requirements/requirements.md
* **Revision History:** https://github.com/ClickHouse/ClickHouse/commits/master/tests/testflows/kerberos/requirements/requirements.md
* **Git:** https://git-scm.com/
* **Kerberos terminology:** https://web.mit.edu/kerberos/kfw-4.1/kfw-4.1/kfw-4.1-help/html/kerberos_terminology.htm
[Kerberos]: https://en.wikipedia.org/wiki/Kerberos_(protocol)
[SPNEGO]: https://en.wikipedia.org/wiki/SPNEGO
[ClickHouse]: https://clickhouse.com
[GitHub]: https://gitlab.com
[GitHub Repository]: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/kerberos/requirements/requirements.md
[Revision History]: https://github.com/ClickHouse/ClickHouse/commits/master/tests/testflows/kerberos/requirements/requirements.md
[Git]: https://git-scm.com/
[Kerberos terminology]: https://web.mit.edu/kerberos/kfw-4.1/kfw-4.1/kfw-4.1-help/html/kerberos_terminology.htm
''')
SRS_001_ClickHouse_Software_Requirements_Specification_Template = Specification(
name='SRS-001 ClickHouse Software Requirements Specification Template',
description=None,
author='[name of the author]',
date='[date]',
status=None,
approved_by=None,
approved_date=None,
approved_version=None,
version=None,
group=None,
type=None,
link=None,
uid=None,
parent=None,
children=None,
headings=(
Heading(name='Revision History', level=1, num='1'),
Heading(name='Introduction', level=1, num='2'),
Heading(name='Table of Contents', level=2, num='2.1'),
Heading(name='Generating HTML version', level=2, num='2.2'),
Heading(name='Generating Python Requirements', level=2, num='2.3'),
Heading(name='Terminology', level=1, num='3'),
Heading(name='SRS', level=2, num='3.1'),
Heading(name='Some term that you will use', level=2, num='3.2'),
Heading(name='Requirements', level=1, num='4'),
Heading(name='RQ.SRS-001.Example', level=2, num='4.1'),
Heading(name='RQ.SRS-001.Example.Subgroup', level=2, num='4.2'),
Heading(name='RQ.SRS-001.Example.Select.1', level=2, num='4.3'),
Heading(name='References', level=1, num='5'),
),
requirements=(
RQ_SRS_001_Example,
RQ_SRS_001_Example_Subgroup,
RQ_SRS_001_Example_Select_1,
),
content='''
# SRS-001 ClickHouse Software Requirements Specification Template
**Author:** [name of the author]
**Date:** [date]
## Table of Contents
* 1 [Revision History](#revision-history)
* 2 [Introduction](#introduction)
* 2.1 [Table of Contents](#table-of-contents)
* 2.2 [Generating HTML version](#generating-html-version)
* 2.3 [Generating Python Requirements](#generating-python-requirements)
* 3 [Terminology](#terminology)
* 3.1 [SRS](#srs)
* 3.2 [Some term that you will use](#some-term-that-you-will-use)
* 4 [Requirements](#requirements)
* 4.1 [RQ.SRS-001.Example](#rqsrs-001example)
* 4.2 [RQ.SRS-001.Example.Subgroup](#rqsrs-001examplesubgroup)
* 4.3 [RQ.SRS-001.Example.Select.1](#rqsrs-001exampleselect1)
* 5 [References](#references)
## Revision History
This document is stored in an electronic form using [Git] source control management software.
## Introduction
This section provides an introduction to the project or the feature.
All [SRS] documents must be uniquely identified by a number. In this
case this document is identified by the number
SRS-001
The document number must always be used as a prefix to the document title. For example,
SRS-xxx Name of the document
All the requirements must be specified in the [Requirements](#requirements) section.
### Table of Contents
Note that currently the table of contents is generated manually using
```bash
cat CH_SRS001_ClickHouse.md | tfs document toc
```
command and needs to be updated any time requirement name is changed
or a new requirement is added.
### Generating HTML version
You can easily generate a pretty HTML version of this document using the command.
```bash
cat CH_SRS001_ClickHouse.md | tfs document convert > CH_SRS001_ClickHouse.html
```
### Generating Python Requirements
You can convert this [SRS] into the `requirements.py` by using the command.
```bash
cat CH_SRS001_ClickHouse.md | tfs requirements generate > requirements.py
```
## Terminology
You can define terminolgy using the examples below and you can make them
linkable as [SRS] by defining the links in the [References](#References) section.
### SRS
Software Requirements Specification
### Some term that you will use
Some description of the term that you would like to use.
## Requirements
This section includes all the requirements. This section can be structured in any way one sees fit.
Each requirement is defined by the section that starts with
the following prefix:
RQ.[document id].[requirement name]
then immediately followed by a one-line block that contains the
the `version` of the requirement.
### RQ.SRS-001.Example
version: 1.0
This is a long description of the requirement that can include any
relevant information.
The one-line block that follows the requirement defines the `version`
of the requirement. The version is controlled manually and is used
to indicate material changes to the requirement that would
require tests that cover this requirement to be updated.
It is a good practice to use requirement names that are broken
up into groups. It is not recommended to use only numbers
because if the requirement must be moved the numbering will not match.
Therefore, the requirement name should start with the group
name which is then followed by a number if any. For example,
RQ.SRS-001.Group.Subgroup.1
To keep names short, try to use abbreviations for the requirement's group name.
### RQ.SRS-001.Example.Subgroup
version: 1.0
This an example of a sub-requirement of the [RQ.SRS-001.Example](#rqsrs-001example).
### RQ.SRS-001.Example.Select.1
version: 1.0
[ClickHouse] SHALL return `1` when user executes query
```sql
SELECT 1
```
## References
* **ClickHouse:** https://clickhouse.com
[SRS]: #SRS
[Some term that you will use]: #Sometermthatyouwilluse
[ClickHouse]: https://clickhouse.com
[Git]: https://git-scm.com/
''')
SRS018_ClickHouse_Map_Data_Type = Specification(
name='SRS018 ClickHouse Map Data Type',
description=None,
author=None,
date=None,
status=None,
approved_by=None,
approved_date=None,
approved_version=None,
version=None,
group=None,
type=None,
link=None,
uid=None,
parent=None,
children=None,
headings=(
Heading(name='Revision History', level=1, num='1'),
Heading(name='Introduction', level=1, num='2'),
Heading(name='Requirements', level=1, num='3'),
Heading(name='General', level=2, num='3.1'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType',
level=3,
num='3.1.1'),
Heading(name='Performance', level=2, num='3.2'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.ArrayOfTuples',
level=3,
num='3.2.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.TupleOfArrays',
level=3,
num='3.2.2'),
Heading(name='Key Types', level=2, num='3.3'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Key.String',
level=3,
num='3.3.1'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Key.Integer',
level=3,
num='3.3.2'),
Heading(name='Value Types', level=2, num='3.4'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Value.String',
level=3,
num='3.4.1'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Value.Integer',
level=3,
num='3.4.2'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Value.Array',
level=3,
num='3.4.3'),
Heading(name='Invalid Types', level=2, num='3.5'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Invalid.Nullable',
level=3,
num='3.5.1'),
Heading(
name='RQ.SRS-018.ClickHouse.Map.DataType.Invalid.NothingNothing',
level=3,
num='3.5.2'),
Heading(name='Duplicated Keys', level=2, num='3.6'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.DuplicatedKeys',
level=3,
num='3.6.1'),
Heading(name='Array of Maps', level=2, num='3.7'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.ArrayOfMaps',
level=3,
num='3.7.1'),
Heading(name='Nested With Maps', level=2, num='3.8'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.NestedWithMaps',
level=3,
num='3.8.1'),
Heading(name='Value Retrieval', level=2, num='3.9'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval',
level=3,
num='3.9.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyInvalid',
level=3,
num='3.9.2'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyNotFound',
level=3,
num='3.9.3'),
Heading(name='Converting Tuple(Array, Array) to Map',
level=2,
num='3.10'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysToMap',
level=3,
num='3.10.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysMap.Invalid',
level=3,
num='3.10.2'),
Heading(name='Converting Array(Tuple(K,V)) to Map',
level=2,
num='3.11'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap',
level=3,
num='3.11.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap.Invalid',
level=3,
num='3.11.2'),
Heading(name='Keys and Values Subcolumns', level=2, num='3.12'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys',
level=3,
num='3.12.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.ArrayFunctions',
level=3,
num='3.12.2'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.InlineDefinedMap',
level=3,
num='3.12.3'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values',
level=3,
num='3.12.4'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.ArrayFunctions',
level=3,
num='3.12.5'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.InlineDefinedMap',
level=3,
num='3.12.6'),
Heading(name='Functions', level=2, num='3.13'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Functions.InlineDefinedMap',
level=3,
num='3.13.1'),
Heading(name='`length`', level=3, num='3.13.2'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.Length',
level=4,
num='3.13.2.1'),
Heading(name='`empty`', level=3, num='3.13.3'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.Empty',
level=4,
num='3.13.3.1'),
Heading(name='`notEmpty`', level=3, num='3.13.4'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.NotEmpty',
level=4,
num='3.13.4.1'),
Heading(name='`map`', level=3, num='3.13.5'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map',
level=4,
num='3.13.5.1'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.InvalidNumberOfArguments',
level=4,
num='3.13.5.2'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MixedKeyOrValueTypes',
level=4,
num='3.13.5.3'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapAdd',
level=4,
num='3.13.5.4'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapSubstract',
level=4,
num='3.13.5.5'),
Heading(
name=
'RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapPopulateSeries',
level=4,
num='3.13.5.6'),
Heading(name='`mapContains`', level=3, num='3.13.6'),
Heading(
name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapContains',
level=4,
num='3.13.6.1'),
Heading(name='`mapKeys`', level=3, num='3.13.7'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapKeys',
level=4,
num='3.13.7.1'),
Heading(name='`mapValues`', level=3, num='3.13.8'),
Heading(name='RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapValues',
level=4,
num='3.13.8.1'),
),
requirements=(
RQ_SRS_018_ClickHouse_Map_DataType,
RQ_SRS_018_ClickHouse_Map_DataType_Performance_Vs_ArrayOfTuples,
RQ_SRS_018_ClickHouse_Map_DataType_Performance_Vs_TupleOfArrays,
RQ_SRS_018_ClickHouse_Map_DataType_Key_String,
RQ_SRS_018_ClickHouse_Map_DataType_Key_Integer,
RQ_SRS_018_ClickHouse_Map_DataType_Value_String,
RQ_SRS_018_ClickHouse_Map_DataType_Value_Integer,
RQ_SRS_018_ClickHouse_Map_DataType_Value_Array,
RQ_SRS_018_ClickHouse_Map_DataType_Invalid_Nullable,
RQ_SRS_018_ClickHouse_Map_DataType_Invalid_NothingNothing,
RQ_SRS_018_ClickHouse_Map_DataType_DuplicatedKeys,
RQ_SRS_018_ClickHouse_Map_DataType_ArrayOfMaps,
RQ_SRS_018_ClickHouse_Map_DataType_NestedWithMaps,
RQ_SRS_018_ClickHouse_Map_DataType_Value_Retrieval,
RQ_SRS_018_ClickHouse_Map_DataType_Value_Retrieval_KeyInvalid,
RQ_SRS_018_ClickHouse_Map_DataType_Value_Retrieval_KeyNotFound,
RQ_SRS_018_ClickHouse_Map_DataType_Conversion_From_TupleOfArraysToMap,
RQ_SRS_018_ClickHouse_Map_DataType_Conversion_From_TupleOfArraysMap_Invalid,
RQ_SRS_018_ClickHouse_Map_DataType_Conversion_From_ArrayOfTuplesToMap,
RQ_SRS_018_ClickHouse_Map_DataType_Conversion_From_ArrayOfTuplesToMap_Invalid,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Keys,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Keys_ArrayFunctions,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Keys_InlineDefinedMap,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Values,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Values_ArrayFunctions,
RQ_SRS_018_ClickHouse_Map_DataType_SubColumns_Values_InlineDefinedMap,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_InlineDefinedMap,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Length,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Empty,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_NotEmpty,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map_InvalidNumberOfArguments,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map_MixedKeyOrValueTypes,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map_MapAdd,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map_MapSubstract,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_Map_MapPopulateSeries,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_MapContains,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_MapKeys,
RQ_SRS_018_ClickHouse_Map_DataType_Functions_MapValues,
),
content='''
# SRS018 ClickHouse Map Data Type
# Software Requirements Specification
## Table of Contents
* 1 [Revision History](#revision-history)
* 2 [Introduction](#introduction)
* 3 [Requirements](#requirements)
* 3.1 [General](#general)
* 3.1.1 [RQ.SRS-018.ClickHouse.Map.DataType](#rqsrs-018clickhousemapdatatype)
* 3.2 [Performance](#performance)
* 3.2.1 [RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.ArrayOfTuples](#rqsrs-018clickhousemapdatatypeperformancevsarrayoftuples)
* 3.2.2 [RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.TupleOfArrays](#rqsrs-018clickhousemapdatatypeperformancevstupleofarrays)
* 3.3 [Key Types](#key-types)
* 3.3.1 [RQ.SRS-018.ClickHouse.Map.DataType.Key.String](#rqsrs-018clickhousemapdatatypekeystring)
* 3.3.2 [RQ.SRS-018.ClickHouse.Map.DataType.Key.Integer](#rqsrs-018clickhousemapdatatypekeyinteger)
* 3.4 [Value Types](#value-types)
* 3.4.1 [RQ.SRS-018.ClickHouse.Map.DataType.Value.String](#rqsrs-018clickhousemapdatatypevaluestring)
* 3.4.2 [RQ.SRS-018.ClickHouse.Map.DataType.Value.Integer](#rqsrs-018clickhousemapdatatypevalueinteger)
* 3.4.3 [RQ.SRS-018.ClickHouse.Map.DataType.Value.Array](#rqsrs-018clickhousemapdatatypevaluearray)
* 3.5 [Invalid Types](#invalid-types)
* 3.5.1 [RQ.SRS-018.ClickHouse.Map.DataType.Invalid.Nullable](#rqsrs-018clickhousemapdatatypeinvalidnullable)
* 3.5.2 [RQ.SRS-018.ClickHouse.Map.DataType.Invalid.NothingNothing](#rqsrs-018clickhousemapdatatypeinvalidnothingnothing)
* 3.6 [Duplicated Keys](#duplicated-keys)
* 3.6.1 [RQ.SRS-018.ClickHouse.Map.DataType.DuplicatedKeys](#rqsrs-018clickhousemapdatatypeduplicatedkeys)
* 3.7 [Array of Maps](#array-of-maps)
* 3.7.1 [RQ.SRS-018.ClickHouse.Map.DataType.ArrayOfMaps](#rqsrs-018clickhousemapdatatypearrayofmaps)
* 3.8 [Nested With Maps](#nested-with-maps)
* 3.8.1 [RQ.SRS-018.ClickHouse.Map.DataType.NestedWithMaps](#rqsrs-018clickhousemapdatatypenestedwithmaps)
* 3.9 [Value Retrieval](#value-retrieval)
* 3.9.1 [RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval](#rqsrs-018clickhousemapdatatypevalueretrieval)
* 3.9.2 [RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyInvalid](#rqsrs-018clickhousemapdatatypevalueretrievalkeyinvalid)
* 3.9.3 [RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyNotFound](#rqsrs-018clickhousemapdatatypevalueretrievalkeynotfound)
* 3.10 [Converting Tuple(Array, Array) to Map](#converting-tuplearray-array-to-map)
* 3.10.1 [RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysToMap](#rqsrs-018clickhousemapdatatypeconversionfromtupleofarraystomap)
* 3.10.2 [RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysMap.Invalid](#rqsrs-018clickhousemapdatatypeconversionfromtupleofarraysmapinvalid)
* 3.11 [Converting Array(Tuple(K,V)) to Map](#converting-arraytuplekv-to-map)
* 3.11.1 [RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap](#rqsrs-018clickhousemapdatatypeconversionfromarrayoftuplestomap)
* 3.11.2 [RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap.Invalid](#rqsrs-018clickhousemapdatatypeconversionfromarrayoftuplestomapinvalid)
* 3.12 [Keys and Values Subcolumns](#keys-and-values-subcolumns)
* 3.12.1 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys](#rqsrs-018clickhousemapdatatypesubcolumnskeys)
* 3.12.2 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.ArrayFunctions](#rqsrs-018clickhousemapdatatypesubcolumnskeysarrayfunctions)
* 3.12.3 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.InlineDefinedMap](#rqsrs-018clickhousemapdatatypesubcolumnskeysinlinedefinedmap)
* 3.12.4 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values](#rqsrs-018clickhousemapdatatypesubcolumnsvalues)
* 3.12.5 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.ArrayFunctions](#rqsrs-018clickhousemapdatatypesubcolumnsvaluesarrayfunctions)
* 3.12.6 [RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.InlineDefinedMap](#rqsrs-018clickhousemapdatatypesubcolumnsvaluesinlinedefinedmap)
* 3.13 [Functions](#functions)
* 3.13.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.InlineDefinedMap](#rqsrs-018clickhousemapdatatypefunctionsinlinedefinedmap)
* 3.13.2 [`length`](#length)
* 3.13.2.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Length](#rqsrs-018clickhousemapdatatypefunctionslength)
* 3.13.3 [`empty`](#empty)
* 3.13.3.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Empty](#rqsrs-018clickhousemapdatatypefunctionsempty)
* 3.13.4 [`notEmpty`](#notempty)
* 3.13.4.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.NotEmpty](#rqsrs-018clickhousemapdatatypefunctionsnotempty)
* 3.13.5 [`map`](#map)
* 3.13.5.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map](#rqsrs-018clickhousemapdatatypefunctionsmap)
* 3.13.5.2 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.InvalidNumberOfArguments](#rqsrs-018clickhousemapdatatypefunctionsmapinvalidnumberofarguments)
* 3.13.5.3 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MixedKeyOrValueTypes](#rqsrs-018clickhousemapdatatypefunctionsmapmixedkeyorvaluetypes)
* 3.13.5.4 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapAdd](#rqsrs-018clickhousemapdatatypefunctionsmapmapadd)
* 3.13.5.5 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapSubstract](#rqsrs-018clickhousemapdatatypefunctionsmapmapsubstract)
* 3.13.5.6 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapPopulateSeries](#rqsrs-018clickhousemapdatatypefunctionsmapmappopulateseries)
* 3.13.6 [`mapContains`](#mapcontains)
* 3.13.6.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapContains](#rqsrs-018clickhousemapdatatypefunctionsmapcontains)
* 3.13.7 [`mapKeys`](#mapkeys)
* 3.13.7.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapKeys](#rqsrs-018clickhousemapdatatypefunctionsmapkeys)
* 3.13.8 [`mapValues`](#mapvalues)
* 3.13.8.1 [RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapValues](#rqsrs-018clickhousemapdatatypefunctionsmapvalues)
## Revision History
This document is stored in an electronic form using [Git] source control management software
hosted in a [GitHub Repository].
All the updates are tracked using the [Revision History].
## Introduction
This software requirements specification covers requirements for `Map(key, value)` data type in [ClickHouse].
## Requirements
### General
#### RQ.SRS-018.ClickHouse.Map.DataType
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type that stores `key:value` pairs.
### Performance
#### RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.ArrayOfTuples
version:1.0
[ClickHouse] SHALL provide comparable performance for `Map(key, value)` data type as
compared to `Array(Tuple(K,V))` data type.
#### RQ.SRS-018.ClickHouse.Map.DataType.Performance.Vs.TupleOfArrays
version:1.0
[ClickHouse] SHALL provide comparable performance for `Map(key, value)` data type as
compared to `Tuple(Array(String), Array(String))` data type where the first
array defines an array of keys and the second array defines an array of values.
### Key Types
#### RQ.SRS-018.ClickHouse.Map.DataType.Key.String
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type where key is of a [String] type.
#### RQ.SRS-018.ClickHouse.Map.DataType.Key.Integer
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type where key is of an [Integer] type.
### Value Types
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.String
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type where value is of a [String] type.
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.Integer
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type where value is of a [Integer] type.
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.Array
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type where value is of a [Array] type.
### Invalid Types
#### RQ.SRS-018.ClickHouse.Map.DataType.Invalid.Nullable
version: 1.0
[ClickHouse] SHALL not support creating table columns that have `Nullable(Map(key, value))` data type.
#### RQ.SRS-018.ClickHouse.Map.DataType.Invalid.NothingNothing
version: 1.0
[ClickHouse] SHALL not support creating table columns that have `Map(Nothing, Nothing))` data type.
### Duplicated Keys
#### RQ.SRS-018.ClickHouse.Map.DataType.DuplicatedKeys
version: 1.0
[ClickHouse] MAY support `Map(key, value)` data type with duplicated keys.
### Array of Maps
#### RQ.SRS-018.ClickHouse.Map.DataType.ArrayOfMaps
version: 1.0
[ClickHouse] SHALL support `Array(Map(key, value))` data type.
### Nested With Maps
#### RQ.SRS-018.ClickHouse.Map.DataType.NestedWithMaps
version: 1.0
[ClickHouse] SHALL support defining `Map(key, value)` data type inside the [Nested] data type.
### Value Retrieval
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval
version: 1.0
[ClickHouse] SHALL support getting the value from a `Map(key, value)` data type using `map[key]` syntax.
If `key` has duplicates then the first `key:value` pair MAY be returned.
For example,
```sql
SELECT a['key2'] FROM table_map;
```
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyInvalid
version: 1.0
[ClickHouse] SHALL return an error when key does not match the key type.
For example,
```sql
SELECT map(1,2) AS m, m[1024]
```
Exceptions:
* when key is `NULL` the return value MAY be `NULL`
* when key value is not valid for the key type, for example it is out of range for [Integer] type,
when reading from a table column it MAY return the default value for key data type
#### RQ.SRS-018.ClickHouse.Map.DataType.Value.Retrieval.KeyNotFound
version: 1.0
[ClickHouse] SHALL return default value for the data type of the value
when there's no corresponding `key` defined in the `Map(key, value)` data type.
### Converting Tuple(Array, Array) to Map
#### RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysToMap
version: 1.0
[ClickHouse] SHALL support converting [Tuple(Array, Array)] to `Map(key, value)` using the [CAST] function.
``` sql
SELECT CAST(([1, 2, 3], ['Ready', 'Steady', 'Go']), 'Map(UInt8, String)') AS map;
```
``` text
┌─map───────────────────────────┐
│ {1:'Ready',2:'Steady',3:'Go'} │
└───────────────────────────────┘
```
#### RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.TupleOfArraysMap.Invalid
version: 1.0
[ClickHouse] MAY return an error when casting [Tuple(Array, Array)] to `Map(key, value)`
* when arrays are not of equal size
For example,
```sql
SELECT CAST(([2, 1, 1023], ['', '']), 'Map(UInt8, String)') AS map, map[10]
```
### Converting Array(Tuple(K,V)) to Map
#### RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap
version: 1.0
[ClickHouse] SHALL support converting [Array(Tuple(K,V))] to `Map(key, value)` using the [CAST] function.
For example,
```sql
SELECT CAST(([(1,2),(3)]), 'Map(UInt8, UInt8)') AS map
```
#### RQ.SRS-018.ClickHouse.Map.DataType.Conversion.From.ArrayOfTuplesToMap.Invalid
version: 1.0
[ClickHouse] MAY return an error when casting [Array(Tuple(K, V))] to `Map(key, value)`
* when element is not a [Tuple]
```sql
SELECT CAST(([(1,2),(3)]), 'Map(UInt8, UInt8)') AS map
```
* when [Tuple] does not contain two elements
```sql
SELECT CAST(([(1,2),(3,)]), 'Map(UInt8, UInt8)') AS map
```
### Keys and Values Subcolumns
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys
version: 1.0
[ClickHouse] SHALL support `keys` subcolumn in the `Map(key, value)` type that can be used
to retrieve an [Array] of map keys.
```sql
SELECT m.keys FROM t_map;
```
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.ArrayFunctions
version: 1.0
[ClickHouse] SHALL support applying [Array] functions to the `keys` subcolumn in the `Map(key, value)` type.
For example,
```sql
SELECT * FROM t_map WHERE has(m.keys, 'a');
```
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Keys.InlineDefinedMap
version: 1.0
[ClickHouse] MAY not support using inline defined map to get `keys` subcolumn.
For example,
```sql
SELECT map( 'aa', 4, '44' , 5) as c, c.keys
```
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values
version: 1.0
[ClickHouse] SHALL support `values` subcolumn in the `Map(key, value)` type that can be used
to retrieve an [Array] of map values.
```sql
SELECT m.values FROM t_map;
```
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.ArrayFunctions
version: 1.0
[ClickHouse] SHALL support applying [Array] functions to the `values` subcolumn in the `Map(key, value)` type.
For example,
```sql
SELECT * FROM t_map WHERE has(m.values, 'a');
```
#### RQ.SRS-018.ClickHouse.Map.DataType.SubColumns.Values.InlineDefinedMap
version: 1.0
[ClickHouse] MAY not support using inline defined map to get `values` subcolumn.
For example,
```sql
SELECT map( 'aa', 4, '44' , 5) as c, c.values
```
### Functions
#### RQ.SRS-018.ClickHouse.Map.DataType.Functions.InlineDefinedMap
version: 1.0
[ClickHouse] SHALL support using inline defined maps as an argument to map functions.
For example,
```sql
SELECT map( 'aa', 4, '44' , 5) as c, mapKeys(c)
SELECT map( 'aa', 4, '44' , 5) as c, mapValues(c)
```
#### `length`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Length
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type as an argument to the [length] function
that SHALL return number of keys in the map.
For example,
```sql
SELECT length(map(1,2,3,4))
SELECT length(map())
```
#### `empty`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Empty
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type as an argument to the [empty] function
that SHALL return 1 if number of keys in the map is 0 otherwise if the number of keys is
greater or equal to 1 it SHALL return 0.
For example,
```sql
SELECT empty(map(1,2,3,4))
SELECT empty(map())
```
#### `notEmpty`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.NotEmpty
version: 1.0
[ClickHouse] SHALL support `Map(key, value)` data type as an argument to the [notEmpty] function
that SHALL return 0 if number if keys in the map is 0 otherwise if the number of keys is
greater or equal to 1 it SHALL return 1.
For example,
```sql
SELECT notEmpty(map(1,2,3,4))
SELECT notEmpty(map())
```
#### `map`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map
version: 1.0
[ClickHouse] SHALL support arranging `key, value` pairs into `Map(key, value)` data type
using `map` function.
**Syntax**
``` sql
map(key1, value1[, key2, value2, ...])
```
For example,
``` sql
SELECT map('key1', number, 'key2', number * 2) FROM numbers(3);
┌─map('key1', number, 'key2', multiply(number, 2))─┐
│ {'key1':0,'key2':0} │
│ {'key1':1,'key2':2} │
│ {'key1':2,'key2':4} │
└──────────────────────────────────────────────────┘
```
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.InvalidNumberOfArguments
version: 1.0
[ClickHouse] SHALL return an error when `map` function is called with non even number of arguments.
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MixedKeyOrValueTypes
version: 1.0
[ClickHouse] SHALL return an error when `map` function is called with mixed key or value types.
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapAdd
version: 1.0
[ClickHouse] SHALL support converting the results of `mapAdd` function to a `Map(key, value)` data type.
For example,
``` sql
SELECT CAST(mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1])), "Map(Int8,Int8)")
```
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapSubstract
version: 1.0
[ClickHouse] SHALL support converting the results of `mapSubstract` function to a `Map(key, value)` data type.
For example,
```sql
SELECT CAST(mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1])), "Map(Int8,Int8)")
```
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.Map.MapPopulateSeries
version: 1.0
[ClickHouse] SHALL support converting the results of `mapPopulateSeries` function to a `Map(key, value)` data type.
For example,
```sql
SELECT CAST(mapPopulateSeries([1,2,4], [11,22,44], 5), "Map(Int8,Int8)")
```
#### `mapContains`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapContains
version: 1.0
[ClickHouse] SHALL support `mapContains(map, key)` function to check weather `map.keys` contains the `key`.
For example,
```sql
SELECT mapContains(a, 'abc') from table_map;
```
#### `mapKeys`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapKeys
version: 1.0
[ClickHouse] SHALL support `mapKeys(map)` function to return all the map keys in the [Array] format.
For example,
```sql
SELECT mapKeys(a) from table_map;
```
#### `mapValues`
##### RQ.SRS-018.ClickHouse.Map.DataType.Functions.MapValues
version: 1.0
[ClickHouse] SHALL support `mapValues(map)` function to return all the map values in the [Array] format.
For example,
```sql
SELECT mapValues(a) from table_map;
```
[Nested]: https://clickhouse.tech/docs/en/sql-reference/data-types/nested-data-structures/nested/
[length]: https://clickhouse.tech/docs/en/sql-reference/functions/array-functions/#array_functions-length
[empty]: https://clickhouse.tech/docs/en/sql-reference/functions/array-functions/#function-empty
[notEmpty]: https://clickhouse.tech/docs/en/sql-reference/functions/array-functions/#function-notempty
[CAST]: https://clickhouse.tech/docs/en/sql-reference/functions/type-conversion-functions/#type_conversion_function-cast
[Tuple]: https://clickhouse.tech/docs/en/sql-reference/data-types/tuple/
[Tuple(Array,Array)]: https://clickhouse.tech/docs/en/sql-reference/data-types/tuple/
[Array]: https://clickhouse.tech/docs/en/sql-reference/data-types/array/
[String]: https://clickhouse.tech/docs/en/sql-reference/data-types/string/
[Integer]: https://clickhouse.tech/docs/en/sql-reference/data-types/int-uint/
[ClickHouse]: https://clickhouse.tech
[GitHub Repository]: https://github.com/ClickHouse/ClickHouse/blob/master/tests/testflows/map_type/requirements/requirements.md
[Revision History]: https://github.com/ClickHouse/ClickHouse/commits/master/tests/testflows/map_type/requirements/requirements.md
[Git]: https://git-scm.com/
[GitHub]: https://github.com
''')