Updated on 2025-05-29 GMT+08:00

Bucket System Functions

gs_redis_get_plan(origin_group_id OID, target_group_id OID)

Description: Obtains a complete migration plan. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

origin_group_id

OID

Source node group.

target_group_id

OID

New node group.

Returned values

Name

Type

Description

sender_id

OID

Source node OID.

sender_name

CSTRING

Name of the source node.

receiver_id

OID

New node OID.

receiver_name

CSTRING

Name of the new node.

bucket_number

INT4

Number of buckets in bucket_list.

bucket_list

OIDVECTOR_EXTEND

List of buckets involved in the migration plan.

Example:

gaussdb=# SELECT * FROM gs_redis_get_plan(16388, 16417);

sender_id | sender_name | receiver_id | receiver_name | bucket_number |                                                                                                                                                                                                                                                                            bucket_list                                                                                                                               
-----------+-------------+-------------+---------------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
     16385 | datanode1   |       16415 | datanode3     |           256 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 18
8 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 2
48 249 250 251 252 253 254 255
     16386 | datanode2   |       16416 | datanode4     |           256 | 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 55
3 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 6
13 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 
673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732
 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767
(2 rows)

gs_redis_get_bucket_statistics

Description: Obtains the log flow transmission status. This can be called only during scale-out and can be queried only by administrators.

Parameter: void

Returned values

Name

Type

Description

bucket_id

OID

Bucket ID.

redis_state

INT1

Scale-out status of the bucket. The value 0 indicates that the scale-out has not started, and the value 1 indicates that the scale-out baseline data has been completed.

xlog_count

INT8

Number of Xlogs generated by the bucket on the original DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

sndr_latest_lsn

INT8

Latest LSN generated by the bucket on the original DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

parser_latest_lsn

INT8

Latest LSN where the bucket is parsed to by the scale-out thread of the original DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

parser_latest_lsn_new

INT8

Latest LSN of bucketxlog where the bucket is parsed to by the scale-out thread of the original DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

rcvr_redo_latest_lsn

INT8

Latest LSN where the bucket is replayed to by the scale-out thread of the new DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

rcvr_redo_latest_lsn_new

INT8

Latest LSN of bucketxlog where the bucket is parsed to by the scale-out thread of the original DN after the current database scale-out starts (that is, after gs_redis_set_distributed_db is called last time).

rcvr_checkpoint

INT8

Checkpoint of the bucket after the current database scale-out starts (that is, after the last calling of gs_redis_set_distributed_db).

rcvr_redo_start_lsn

INT8

Original LSN for starting the replay of the bucket after the scale-out of the current database starts (that is, after the last calling of gs_redis_set_distributed_db).

rcvr_redo_end_lsn

INT8

Original LSN for ending the replay of the bucket after the scale-out of the current database starts (that is, after the last calling of gs_redis_set_distributed_db).

Example:

gaussdb=#  SELECT * FROM gs_redis_get_bucket_statistics();
 bucket_id | redis_state | xlog_count | sndr_latest_lsn | parser_latest_lsn | parser_latest_lsn_new | rcvr_redo_latest_lsn | rcvr_redo_latest_lsn_new | rcvr_checkpoint | rcvr_redo_start_lsn | rcvr_redo_end_lsn
-----------+-------------+------------+-----------------+-------------------+-----------------------+----------------------+--------------------------+-----------------+
--------------------+-------------------
         0 | 1           |          1 |        79303808 |          79303808 |              16777352 |             79326320 |                 16801904 |       762624525 |
           77256412 |          79326320
         1 | 1           |          1 |        79303896 |          79303896 |              16777448 |             79326320 |                 16801904 |       762624525 |
           77256412 |          79326320
         2 | 1           |          1 |        79303984 |          79303984 |              16777544 |             79326320 |                 16801904 |       762624525 |
           77256412 |          79326320
         3 | 1           |          1 |        79304072 |          79304072 |              16777640 |             79326320 |                 16801904 |       762624525 |
           77256412 |          79326320
         4 | 1           |          1 |        79304160 |          79304160 |              16777736 |             79326320 |                 16801904 |       762624525 |
           77256412 |          79326320
(Only part of the data is displayed.)

gs_redis_set_distributed_db(db_name CSTRING, bucketgroup SMALLINT)

Description: Sets the database and bucket group that are being redistributed using a hash bucket. This can be called only on DNs during scale-out and can be queried only by administrators.

Parameters:

  • db_name: specifies the name of the database to be redistributed.

Return type: void

Example:

gaussdb=# SELECT gs_redis_set_distributed_db('gaussdb', 0);
 gs_redis_set_distributed_db 
-----------------------------
0
(1 row)

gs_redis_hashbucket_update_segment_header(origin_group_id OID, target_group_id OID)

Description: Updates the headers of all hash bucket tables in the current database. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

origin_group_id

OID

Source node group.

target_group_id

OID

New node group.

Return type: Boolean

Example:

gaussdb=#  SELECT * FROM gs_redis_hashbucket_update_segment_header(16388, 16417);
 gs_redis_hashbucket_update_segment_header 
-------------------------------------------
 t
(1 row)

gs_redis_local_get_segment_header(table_name REGCLASS, bucketlist OIDVECTOR_EXTEND)

Description: Obtains the header of a segment-page table. It can be called only on DNs.

The following describes the parameters.

Name

Type

Description

table_name

REGCLASS

Table name.

bucketlist

OIDVECTOR_EXTEND

Bucket list.

Return type: header_info

Example:

gaussdb=#  SELECT * FROM gs_redis_local_get_segment_header('mytable', '256');
 gs_redis_local_get_segment_header
----------------------------------------------------------------------------------------------------------------------------
4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295,4294967295, ... (Only part of the data is displayed.)
(1 row)

gs_redis_local_update_segment_header(table_name REGCLASS, header_info CSTRING)

Description: Updates the header of a segment-page table. It can be called only on DNs.

The following describes the parameters.

Name

Type

Description

table_name

REGCLASS

Table name.

header_info

CSTRING

Header of a segment-page table.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_local_update_segment_header('mytable', '4294967295,4294967295,4294967295,4294967295, ....'); (Only part of the data is displayed.)
 gs_redis_local_update_segment_header
-------------------------------------------
 0 
(1 row)

gs_redis_hashbucket_update_inverse_pointer(buckets TEXT, origin_dn_name TEXT, new_dn_name TEXT)

Description: Updates the inverse pointers of buckets of this batch in all hash bucket tables in the current database. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

buckets

TEXT

List of buckets that are brought online this time.

origin_dn_name

TEXT

Source node name.

new_dn_name

TEXT

New node name.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_hashbucket_update_inverse_pointer('0,1,2,3,4,5,6,7,8,9,10','datanode1','datanode3');
 gs_redis_hashbucket_update_inverse_pointer
-------------------------------------------
 0 
(1 row)

gs_redis_local_get_inverse_pointer(buckets TEXT, origin_dn_name TEXT, new_dn_name TEXT)

Description: Obtains the inverse pointer. This can be called only on DNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

buckets

TEXT

List of buckets that are brought online this time.

origin_dn_name

TEXT

Source node name.

new_dn_name

TEXT

New node name.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_hashbucket_update_inverse_pointer('0,1,2,3,4,5,6,7,8,9,10','datanode1','datanode3');
 gs_redis_hashbucket_update_inverse_pointer
-------------------------------------------
 0 
(1 row)

gs_redis_local_update_inverse_pointer(table_name TEXT, header_info TEXT, bucketlist TEXT)

Description: Records Xlogs for updating inverse pointers. This can be called only on DNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

table_name

REGCLASS

Table name.

header_info

TEXT

Header of a segment-page table.

bucketlist

TEXT

Bucket list.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_local_update_inverse_pointer('mytable', '4294967295,4294967295,4294967295,4294967295, ....','1 2 3'); (Only part of the data is displayed.)
 gs_redis_local_update_inverse_pointer
-------------------------------------------
 0 
(1 row)

gs_redis_local_set_hashbucket_frozenxid

Description: Changes the relfrozenxid64 value of the hash bucket table in the system catalog. This can be called only on DNs during scale-out and can be queried only by administrators.

Parameter description: void

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_local_set_hashbucket_frozenxid();
 gs_redis_local_set_hashbucket_frozenxid
-------------------------------------------
 0 
(1 row)

gs_redis_set_hashbucket_frozenxid(origin_group_id OID, target_group_id OID)

Description: Changes the relfrozenxid64 value of the hash bucket table in the system catalog on the new DN. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

origin_group_id

OID

Source node group.

target_group_id

OID

New node group.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_set_hashbucket_frozenxid(16388, 16417);
 gs_redis_set_hashbucket_frozenxid
-------------------------------------------
 0
(1 row)

gs_redis_set_nextxid(xid BIGINT)

Description: Modifies the next_xid value of a DN. It can be called only on DNs during scale-out and can be queried only by administrators.

Parameter: xid indicates the expected value of next_xid.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_set_nextxid('15268817');
 gs_redis_set_nextxid
-------------------------------------------
 0
(1 row)

gs_redis_set_csn(csn BIGINT)

Description: Changes the next_csn value of a DN. This API can be called only during scale-out. It can be queried only by administrators. It can be called only on DNs. It can be called only in GTM_FREE mode.

Parameters:

  • csn: specifies the expected value of next_csn.

Return type: void

Example:

gaussdb=#  SELECT * FROM gs_redis_set_csn('15268817');
 gs_redis_set_csn
-------------------------------------------
 0
(1 row)

gs_redis_check_bucket_flush(dn_array NAME[])

Description: Determines whether all private buffers for RTO replay are flushed. This can be called only during scale-out and can be queried only by administrators.

Parameters:

  • dn_array: specifies the DN name list.

Return type: Boolean

Example:

gaussdb=#  SELECT * FROM gs_redis_check_bucket_flush('{datanode1, datanode2}');
 gs_redis_check_bucket_flush 
-----------------------------
 f
(1 row)

gs_redis_get_flush_page_lsn(isclean bool)

Description: Queries the page refreshing information of bucket scale-out replay.

Permission: It can be called only in the debug version during scale-out and queried only by system administrators.

Parameter: isclean specifies whether to clear page refreshing information. The value is of the Boolean type.

Returned values

Name

Type

Description

node_name

TEXT

DN where the page is located.

space_id

OID

Tablespace ID.

db_id

OID

Database ID.

file_id

OID

Data file ID. The value ranges from 1 to 5.

bucket_id

OID

Bucket partition ID. The value ranges from 0 to 1023.

forknum

OID

Data file fork. The value ranges from 0 to 2.

blocknum

OID

Offset page number of the physical page in the data file.

latest_flush_lsn

UINT8

Latest LSN of the dirty page.

Example:

gaussdb=#  SELECT * FROM gs_redis_get_flush_page_lsn(false);
 node_name | space_id | db_id | file_id | bucket_id | forknum | blocknum | last_flush_lsn
-------------------------------------------------------------------------------------------
 datanode2 |     1633 | 16387 |       1 |        66 |       0 |       20 |     1571838992
(1 row)

gs_redis_show_bucketxid(bucketid_list OIDVECTOR_EXTEND)

Description: Queries the bucketxid corresponding to a specified bucket. This can be called only on DNs during scale-out and can be queried only by administrators.

Parameters:

  • bucketid_list: specifies the bucket list.

Return type: CString

Example:

gaussdb=#  SELECT * FROM gs_redis_show_bucketxid('1 2 3');
 gs_redis_show_bucketxid
----------------------------
 88880001 88880001 88880001
(1 row)

bucket_lock_status

Description: Queries information about bucket locks held by open transactions. All users can execute this function.

Parameter description: void

Returned values

Name

Type

Description

database

oid

OID of the database in which the locked target exists.

virtualtransaction

text

Virtual ID of the transaction holding or awaiting this lock.

pid

bigint

Logical ID of the server thread holding or awaiting this lock. The value is NULL if the lock is held by a prepared transaction.

sessionid

bigint

ID of the session holding or awaiting this lock.

mode

text

Lock mode held or desired by this thread.

The options are AccessShareLock and AccessExclusiveLock.

granted

boolean

  • The value is TRUE if the lock is a held lock.
  • The value is FALSE if the lock is an awaited lock.

fastpath

boolean

The value is TRUE if the lock is obtained through fast-path. The value is FALSE if the lock is obtained through database-level lock information or two-phase commit.

global_sessionid

text

Global session ID.

bucketlist

text

Location of the locked bucket in the bucket group.

bucket_group

smallint

Bucket group to which the locked bucket belongs.

Example:

gaussdb=# SELECT * FROM bucket_lock_status();
 database | virtualtransaction |       pid       | sessionid |      mode       | granted | fastpath | global_sessionid | bucketlist | bucket_group
----------+--------------------+-----------------+-----------+-----------------+---------+----------+------------------+------------+--------------
    14934 | 8/25               | 140376742557440 |         2 | AccessShareLock | t       | t        | 1938253334:2#0   | (977,978)  |            2
(1 row)

gs_redis_parse_slicebucket_tranfer_file(plan_json CSTRING, type CSTRING)

Description: Obtains the slice bucket migration plan. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

plan_json

TEXT

Slice migration file specified by the user.

type

CSTRING

Plan type, which can be 'incremental' or 'full'. The default value is 'full'.

The following describes the return types.

Name

Type

Description

idx

INT

ID of the database to be migrated.

database_name

CSTRING

Name of the database to be migrated.

Example:

gaussdb=# SELECT gs_redis_parse_slicebucket_tranfer_file('filepath', 'full');
| idx| database_name|
----------------------------
| 0| tpcc1000w|
(1 row)

gs_redis_get_slicebucket_plan()

Description: Obtains the slice bucket migration plan of the current database. This can be called only on CNs during scale-out and can be queried only by administrators.

Parameter: void

Returned values

Name

Type

Description

sender_id

OID

OID of the source node.

sender_name

CSTRING

Name of the source node.

receiver_id

OID

OID of the target node.

receiver_name

CSTRING

Name of the new node.

bucket_number

INT4

Number of buckets in bucket_list.

bucket_list

OIDVECTOR_EXTEND

List of buckets involved in the migration plan.

bucketgroup

OID

Group to which the bucket in the bucket list belongs. The value ranges from 0 to 4.

Example:

gaussdb=# SELECT gs_redis_get_slicebucket_plan();
| sender_id| sender_name| receiver_id| receiver_name| bucket_number| bucket_list| bucketgroup|
--------------------------------------------------------------------------------------------------
| 16385| datanode1| 32768| datanode3| 1| 2048| 1|
--------------------------------------------------------------------------------------------------
| 16386| datanode2| 32768| datanode3| 1| 2049| 1|
--------------------------------------------------------------------------------------------------
| 16386| datanode2| 32768| datanode3| 4| 3073 3076 3079 3082| 2|
--------------------------------------------------------------------------------------------------
| 16385| datanode1| 32768| datanode3| 1| 3074| 2|
--------------------------------------------------------------------------------------------------
| 16385| datanode1| 32768| datanode3| 4| 4098 4099 4101 4102| 3|
(5 rows)

gs_redis_slicebucket_update_segment_header()

Description: Updates the headers of all slice bucket tables in the current database. This can be called only on CNs during scale-out and can be queried only by administrators.

Input parameter: void

Return type: Boolean

Example:

gaussdb=#  SELECT * FROM gs_redis_slicebucket_update_segment_header();
 gs_redis_slicebucket_update_segment_header 
-------------------------------------------
 t
(1 row)

gs_redis_drop_bucket_files(plan_json CSTRING)

Description: Deletes the range bucket files that have been physically migrated from the source node. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

plan_json

CSTRING

Slice migration file specified by the user.

Return type: Boolean

Example:

gaussdb=# SELECT gs_redis_drop_bucket_files('filepath');
 gs_redis_drop_bucket_files
-------------------------------------------
 t
(1 row)

gs_redis_drop_bucket_files(origin_group_id OID, target_group_id OID)

Description: Deletes the files that have been physically migrated from the source node. This can be called only on CNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

origin_group_id

OID

Source node group.

target_group_id

OID

New node group.

Return type: Boolean

Example:

gaussdb=# SELECT * FROM gs_redis_drop_bucket_files(16388, 16417);
 gs_redis_drop_bucket_files
-------------------------------------------
 t
(1 row)

gs_redis_local_drop_bucket_files(bucketlist CSTRING, bucketnum SMALLINT)

Description: Deletes the corresponding bucket list from the hash bucket table. This can be called only on DNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

bucketlist

CSTRING

Specified bucket list.

bucketnum

SMALLINT

Number of buckets.

Return type: Boolean

Example:

gaussdb=# SELECT * FROM gs_redis_local_drop_bucket_files('1 2 3', 3);
 gs_redis_local_drop_bucket_files
-------------------------------------------
 t
(1 row)

gs_redis_local_drop_bucket_files(database_name NAME, bucketlist CSTRING, bucketnum SMALLINT)

Description: Deletes the bucket list of the corresponding database from the range bucket table. This can be called only on DNs during scale-out and can be queried only by administrators.

The following describes the parameters.

Name

Type

Description

database_name

NAME

Specified database name.

bucketlist

CSTRING

Specified bucket list.

bucketnum

SMALLINT

Number of buckets.

Return type: Boolean

Example:

gaussdb=# SELECT gs_redis_local_drop_bucket_files('postgres', '1 2 3', 3);
 gs_redis_local_drop_bucket_files
-------------------------------------------
 t
(1 row)