add documentation for tidb_decode_key

[kolbe]

Change Request

Please answer the following questions before submitting your issue. Thanks!

1. Describe what you find is inappropriate or missing in the existing docs.

The tidb_decode_key function is very useful for mapping a raw key back to the table/index it belongs to. This function should be documented so that its behavior and limitations (pingcap/tidb#23180 for example) are well-understood.

[TomShawn]

/assign @tangenta @wjhuang2016 @bb7133
Anyone can add doc content for tidb_decode_key?

[wjhuang2016]

The problem is that, do we expect users to know this function?

[tangenta]

For now, we don't have a page to introduce the built-in functions in detail. Where should I put the documentation of tidb_decode_key?

The tidb_decode_key function is very useful for mapping a raw key back to the table/index it belongs to.

@kolbe Do you know where the raw keys usually come from? We can put the explanation to the related tutorials.

[kolbe]

@tangenta I don't think an explanation needs to be provided in any tutorials, I think we simply need documentation about what the function does, its limitations, etc.

[dveeden]

https://docs.pingcap.com/tidb/stable/tidb-functions#tidb_decode_key
#5699

Can we close this now or is there something missing?

[kolbe]

@dveeden I think the description in the docs should be extended a bit to include the expected output when the schema does not use a "hidden" row id. For example, a compound clustered primary key:

tidb> show create table t2\G
*************************** 1. row ***************************
       Table: t2
Create Table: CREATE TABLE `t2` (
  `id` binary(36) NOT NULL,
  `a` tinyint(3) unsigned NOT NULL,
  `v` varchar(512) DEFAULT NULL,
  PRIMARY KEY (`a`,`id`) /*T![clustered_index] CLUSTERED */
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
1 row in set (0.001 sec)

tidb> select * from information_schema.tikv_region_status where table_name='t2' limit 1\G
*************************** 1. row ***************************
                REGION_ID: 48
                START_KEY: 7480000000000000FF3E5F720400000000FF0000000601633430FF3338646232FF2D64FF3531632D3131FF65FF622D386337352DFFFF3830653635303138FFFF61396265000000FF00FB000000000000F9
                  END_KEY:
                 TABLE_ID: 62
                  DB_NAME: test
               TABLE_NAME: t2
                 IS_INDEX: 0
                 INDEX_ID: NULL
               INDEX_NAME: NULL
           EPOCH_CONF_VER: 1
            EPOCH_VERSION: 38
            WRITTEN_BYTES: 0
               READ_BYTES: 0
         APPROXIMATE_SIZE: 136
         APPROXIMATE_KEYS: 479905
  REPLICATIONSTATUS_STATE: NULL
REPLICATIONSTATUS_STATEID: NULL
1 row in set (0.005 sec)

tidb> select tidb_decode_key('7480000000000000FF3E5F720400000000FF0000000601633430FF3338646232FF2D64FF3531632D3131FF65FF622D386337352DFFFF3830653635303138FFFF61396265000000FF00FB000000000000F9');
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| tidb_decode_key('7480000000000000FF3E5F720400000000FF0000000601633430FF3338646232FF2D64FF3531632D3131FF65FF622D386337352DFFFF3830653635303138FFFF61396265000000FF00FB000000000000F9') |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| {"handle":{"a":"6","id":"c4038db2-d51c-11eb-8c75-80e65018a9be"},"table_id":62}                                                                                                        |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row in set (0.001 sec)