add more docs

Author: TomShawn

docs/sys-catalogs/sys-tables/sys-tbl-pg-amproc.md

@@ -0,0 +1,16 @@
+---
+title: pg_amproc
+---
+
+# pg_amproc
+
+The `pg_amproc` table in the `pg_catalog` schema stores information about support procedures associated with index access method operator classes. There is one row for each support procedure belonging to an operator class.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`oid`|oid| |Row identifier (hidden attribute; must be explicitly selected)|
+|`amprocfamily`|oid|`pg_opfamily.oid`|The operator family this entry is for|
+|`amproclefttype`|oid|`pg_type.oid`|Left-hand input data type of associated operator|
+|`amprocrighttype`|oid|`pg_type.oid`|Right-hand input data type of associated operator|
+|`amprocnum`|smallint| |Support procedure number|
+|`amproc`|regproc|`pg_proc.oid`|OID of the procedure|

docs/sys-catalogs/sys-tables/sys-tbl-pg-appendonly.md

@@ -0,0 +1,21 @@
+---
+title: pg_appendonly
+---
+
+The `pg_appendonly` table in the `pg_catalog` schema contains information about the storage options and other characteristics of append-optimized tables.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`relid`|oid| |The table object identifier \(OID\) of the table.|
+| `blocksize` | integer |  | Block size used for compression of append-optimized tables. Valid values are 8K - 2M. Default is `32K`. |
+| `safefswritesize` | integer| | Minimum size for safe write operations to append-optimized tables in a non-mature file system. Commonly set to a multiple of the extent size of the file system; for example, Linux ext3 is `4096` bytes, so a value of `32768` is commonly used. |
+| `compresslevel`|smallint| |The compression level, with compression ratio increasing from 1 to 19. When quicklz1 is specified for compresstype, valid values are 1 or 3. With zlib specified, valid values are 1-9. When zstd is specified, valid values are 1-19. |
+| `checksum`|boolean| |A checksum value that is stored to compare the state of a block of data at compression time and at scan time to ensure data integrity. |
+| `compresstype`|text| |Type of compression used to compress append-optimized tables. Valid values are: <br /> - `none` (no compression)<br /> - `rle_type` (run-length encoding compression) <br />- `zlib` (gzip compression) <br />- `zstd` (Zstandard compression)<br /> - `quicklz` |
+| `columnstore` | boolean |  | `1` for column-oriented storage, `0` for row-oriented storage. |
+| `segrelid` | oid | |Table on-disk segment file id. |
+| `segfilecount` |  smallint| |Number of segment files. |
+| `blkdirrelid` | oid | |Block used for on-disk column-oriented table file. |
+| `blkdiridxid` | oid | |Block used for on-disk column-oriented index file. |
+| `visimaprelid` | oid | |Visibility map for the table. |
+| `visimapidxid` | oid | |B-tree index on the visibility map. |

docs/sys-catalogs/sys-tables/sys-tbl-pg-attribute-encoding.md

@@ -0,0 +1,19 @@
+---
+title: pg_attribute_encoding
+---
+
+# pg_attribute_encoding
+
+The `pg_attribute_encoding` system catalog table in the `pg_catalog` schema contains column storage information.
+
+|column|type|modifers|storage|description|
+|------|----|--------|-------|-----------|
+|`attrelid`|oid|not null|plain|Foreign key to `pg_attribute.attrelid`|
+|`attnum`|smallint|not null|plain|Foreign key to `pg_attribute.attnum`|
+|`attoptions`|text [ ]| |extended|The options|
+
+For a column with `filenum = f`, the column files on disk use the suffix `(f - 1)*128 to f*128 - 1`. For example:
+
+- Column with `filenum = 1` has files `relfilenode`, `relfilenode.1` .. `relfilenode.127`.
+- Column with `filenum = 2` has files `relfilenode.128`, `relfilenode.129` .. `relfilenode.255`.
+- Column with `filenum = 3` has files `relfilenode.256`, `relfilenode.257` .. `relfilenode.383`.

docs/sys-catalogs/sys-tables/sys-tbl-pg-attribute.md

@@ -0,0 +1,36 @@
+---
+title: pg_attribute
+---
+
+The `pg_attribute` table in the `pg_catalog` schema stores information about table columns. There will be exactly one `pg_attribute` row for every column in every table in the database. (There will also be attribute entries for indexes, and all objects that have `pg_class` entries.) The term attribute is equivalent to column.
+
+In a dropped column's `pg_attribute` entry, `atttypid` is reset to zero, but `attlen` and the other fields copied from `pg_type` are still valid. This arrangement is needed to address the situation where the dropped column's data type was later dropped, and so there is no `pg_type` row anymore. `attlen` and the other fields can be used to interpret the contents of a row of the table.
+
+|Column|Type|References|Description|
+|------|----|----------|-----------|
+|`attrelid`|oid|`pg_class.oid`|The table this column belongs to.|
+|`attname`|name| |The column name.|
+|`atttypid`|oid|`pg_type.oid`|The data type of this column.|
+|`attstattarget`|integer| |Controls the level of detail of statistics accumulated for this column by `ANALYZE`. A zero value indicates that no statistics should be collected. A negative value says to use the system default statistics target. The exact meaning of positive values is data type-dependent. For scalar data types, it is both the target number of "most common values" to collect, and the target number of histogram bins to create.|
+|`attlen`|smallint| |A copy of `pg_type.typlen` of this column's type.|
+|`attnum`|smallint| |The number of the column. Ordinary columns are numbered from 1 up. System columns, such as `ctid`, have (arbitrary) negative numbers.|
+|`attndims`|integer| |Number of dimensions, if the column is an array type; otherwise `0`. (Currently, the number of dimensions of an array is not enforced, so any nonzero value effectively means it is an array.)|
+|`attcacheoff`|integer| |Always `-1` in storage, but when loaded into a row descriptor in memory this may be updated to cache the offset of the attribute within the row.|
+|`atttypmod`|integer| |Records type-specific data supplied at table creation time (for example, the maximum length of a `varchar` column). It is passed to type-specific input functions and length coercion functions. The value will generally be `-1` for types that do not need it.|
+|`attbyval`|boolean| |A copy of `pg_type.typbyval` of this column's type.|
+|`attstorage`|char| |Normally a copy of `pg_type.typstorage` of this column's type. For TOAST-able data types, this can be altered after column creation to control storage policy.|
+|`attalign`|char| |A copy of `pg_type.typalign` of this column's type.|
+|`attnotnull`|boolean| |This represents a not-null constraint. |
+| `attcompression` | char | | Compression type for this column. Valid values are `n` for none, `r` for run-length encoding, `z` for zlib, `q` for quicklz, and `s` for snappy. |
+|`atthasdef`|boolean| |This column has a default expression or generation expression, in which case there will be a corresponding entry in the `pg_attrdef` catalog that actually defines the value. (Check `attgenerated` to determine whether this is a default or a generation expression.)|
+|`atthasmissing`|boolean| |This column has a value which is used where the column is entirely missing from the row, as happens when a column is added with a non-volatile `DEFAULT` value after the row is created. The actual value used is stored in the `attmissingval` column.|
+|`attidentity`|char| |If a zero byte (''), then not an identity column. Otherwise, `a` = generated always, `d` = generated by default.|
+|`attgenerated`|char| |If a zero byte (''), then not a generated column. Otherwise, `s` = stored. (Other values might be added in the future.) |
+|`attisdropped`|boolean| |This column has been dropped and is no longer valid. A dropped column is still physically present in the table, but is ignored by the parser and so cannot be accessed via SQL.|
+|`attislocal`|boolean| |This column is defined locally in the relation. Note that a column may be locally defined and inherited simultaneously.|
+|`attinhcount`|integer| |The number of direct ancestors this column has. A column with a nonzero number of ancestors cannot be dropped nor renamed.|
+|`attcollation`|oid|`pg_collation.oid`|The defined collation of the column, or zero if the is not of a collatable data type.|
+|`attacl`|aclitem[]| |Column-level access privileges, if any have been granted specifically on this column.|
+|`attoptions`|text[]| |Attribute-level options, as "keyword=value" strings.|
+|`attfdwoptions`|text[]| |Attribute-level foreign data wrapper options, as "keyword=value" strings.|
+|`attmissingval`|anyarray| |This column has a one element array containing the value used when the column is entirely missing from the row, as happens when the column is added with a non-volatile `DEFAULT` value after the row is created. The value is only used when `atthasmissing` is `true`. If there is no value the column is null.|

docs/sys-catalogs/sys-tables/sys-tbl-pg-attridef.md

@@ -0,0 +1,14 @@
+---
+title: pg_attrdef
+---
+
+# pg_attrdef
+
+The `pg_attrdef` table in the `pg_catalog` schema stores column default values. The main information about columns is stored in `pg_attribute`. Only columns that explicitly specify a default value (when the table is created or the column is added) will have an entry here.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`oid`|oid| |The object ID|
+|`adrelid`|oid| `pg_class.oid` |The table this column belongs to|
+|`adnum`|smallint| `pg_attribute.attnum` |The number of the column|
+|`adbin`|pg_node_tree| |The internal representation of the column default value|

docs/sys-catalogs/sys-tables/sys-tbl-pg-auth-members.md

@@ -0,0 +1,14 @@
+---
+title: pg_auth_members
+---
+
+# pg_auth_members
+
+The `pg_auth_members` system catalog table in the `pg_catalog` schema shows the membership relations between roles. Any non-circular set of relationships is allowed. Because roles are system-wide, `pg_auth_members` is shared across all databases of a Cloudberry Database system.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`roleid`|oid|`pg_authid.oid`|ID of the parent-level (group) role|
+|`member`|oid|`pg_authid.oid`|ID of a member role|
+|`grantor`|oid|`pg_authid.oid`|ID of the role that granted this membership|
+|`admin_option`|boolean| |True if role member might grant membership to others|

docs/sys-catalogs/sys-tables/sys-tbl-pg-authid.md

@@ -0,0 +1,31 @@
+---
+title: pg_authid
+---
+
+# pg_authid
+
+The `pg_authid` table in the `pg_catalog` schema contains information about database authorization identifiers (roles). A role subsumes the concepts of users and groups. A user is a role with the `rolcanlogin` flag set. Any role (with or without `rolcanlogin`) might have other roles as members. See [`pg_auth_members`](/docs/sys-catalogs/sys-tables/sys-tbl-pg-auth-members.md).
+
+Because this catalog contains passwords, it must not be publicly readable. `pg_roles` is a publicly readable view on `pg_authid` that blanks out the password field.
+
+Because user identities are system-wide, `pg_authid` is shared across all databases in a Cloudberry Database system: there is only one copy of `pg_authid` per system, not one per database.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`oid`|oid| |Row identifier|
+|`rolname`|name| |Role name|
+|`rolsuper`|boolean| |Role has superuser privileges|
+|`rolinherit`|boolean| |Role automatically inherits privileges of roles it is a member of|
+|`rolcreaterole`|boolean| |Role might create more roles|
+|`rolcreatedb`|boolean| |Role might create databases|
+|`rolcanlogin`|boolean| |Role might log in. That is, this role can be given as the initial session authorization identifier|
+|`rolreplication`|boolean| |Role is a replication role. That is, this role can initiate streaming replication and set/unset the system backup mode using `pg_start_backup` and `pg_stop_backup`.|
+|`rolbypassrls`|boolean| |Roles bypasses every row-level security policy.|
+|`rolconnlimit`|int4| |For roles that can log in, this sets maximum number of concurrent connections this role can make. `-1` means no limit|
+|`rolpassword`|text| |Password (possibly encrypted); NULL if none. If the password is encrypted, this column will begin with the string `md5` followed by a 32-character hexadecimal MD5 hash. The MD5 hash will be the user's password concatenated to their user name. For example, if user `joe` has password `xyzzy`, Cloudberry Database will store the md5 hash of `xyzzyjoe`. Cloudberry Database assumes that a password that does not follow that format is unencrypted.|
+|`rolvaliduntil`|timestamptz| |Password expiry time (only used for password authentication); NULL if no expiration|
+|`rolresqueue`|oid| |Object ID of the associated resource queue ID in `pg_resqueue` |
+|`rolcreaterextgpfd`|boolean| |Privilege to create read external tables with the `gpfdist` or `gpfdists` protocol|
+|`rolcreaterexhttp`|boolean| |Privilege to create read external tables with the `http` protocol|
+|`rolcreatewextgpfd`|boolean| |Privilege to create write external tables with the `gpfdist` or `gpfdists` protocol|
+|`rolresgroup`|oid| |Object ID of the associated resource group ID in `pg_resgroup` |

docs/sys-catalogs/sys-tables/sys-tbl-pg-cast.md

@@ -0,0 +1,24 @@
+---
+title: pg_cast
+---
+
+# pg_cast
+
+The `pg_cast` table in the `pg_catalog` schema stores data type conversion paths, both built-in paths and those defined with `CREATE CAST`.
+
+Note that `pg_cast` does not represent every type conversion known to the system, only those that cannot be deduced from some generic rule. For example, casting between a domain and its base type is not explicitly represented in `pg_cast`. Another important exception is that "automatic I/O conversion casts", those performed using a data type's own I/O functions to convert to or from `text` or other string types, are not explicitly represented in `pg_cast`.
+
+The cast functions listed in `pg_cast` must always take the cast source type as their first argument type, and return the cast destination type as their result type. A cast function can have up to three arguments. The second argument, if present, must be type `integer`; it receives the type modifier associated with the destination type, or `-1` if there is none. The third argument, if present, must be type `boolean`; it receives `true` if the cast is an explicit cast, `false` otherwise.
+
+It is legitimate to create a `pg_cast` entry in which the source and target types are the same, if the associated function takes more than one argument. Such entries represent 'length coercion functions' that coerce values of the type to be legal for a particular type modifier value.
+
+When a `pg_cast` entry has different source and target types and a function that takes more than one argument, the entry converts from one type to another and applies a length coercion in a single step. When no such entry is available, coercion to a type that uses a type modifier involves two steps, one to convert between data types and a second to apply the modifier.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`oid`|oid||The object ID.|
+|`castsource`|oid|`pg_type.oid`|OID of the source data type.|
+|`casttarget`|oid|`pg_type.oid`|OID of the target data type.|
+|`castfunc`|oid|`pg_proc.oid`|The OID of the function to use to perform this cast. Zero is stored if the cast method does not require a function.|
+|`castcontext`|char| |Indicates what contexts the cast may be invoked in. `e` means only as an explicit cast (using `CAST` or `::` syntax). `a` means implicitly in assignment to a target column, as well as explicitly. `i` means implicitly in expressions, as well as the other cases*.*|
+|`castmethod`|char| |Indicates how the cast is performed:<br/><br/>`f` - The function identified in the `castfunc` field is used.<br/><br/>`i` - The input/output functions are used.<br/><br/>`b` - The types are binary-coercible, and no conversion is required.|

docs/sys-catalogs/sys-tables/sys-tbl-pg-class.md

@@ -0,0 +1,45 @@
+---
+title: pg_class
+---
+
+# pg_class
+
+The system catalog table `pg_class` catalogs tables and most everything else that has columns or is otherwise similar to a table. This includes indexes (see also `pg_index`), sequences, views, materialized views, composite types, and TOAST tables. Below, when we mean all of these kinds of objects we speak of "relations". Not all columns are meaningful for all relation types.
+
+|column|type|references|description|
+|------|----|----------|-----------|
+|`oid`|oid| |Row identifier|
+|`relname`|name| |Name of the table, index, view.|
+|`relnamespace`|oid| `pg_namespace.oid` |The object identifier of the namespace (schema) that contains this relation|
+|`reltype`|oid| `pg_type.oid` |The object identifier of the data type that corresponds to this table's row type, if any (zero for indexes, which have no `pg_type` entry)|
+|`reloftype`|oid| `pg_type.oid` |For typed tables, the object identifier of the underlying composite type, zero for all other relations|
+|`relowner`|oid|`pg_authid.oid`|Owner of the relation|
+|`relam`|oid|`pg_am.oid`|If this is a table or an index, the access method used (heap, B-tree, hash.)|
+|`relfilenode`|oid| |Name of the on-disk file of this relation; zero means this is a "mapped" relation whose disk file name is determined by low-level state|
+|`reltablespace`|oid|`pg_tablespace.oid`|The tablespace in which this relation is stored. If zero, the database's default tablespace is implied. (Not meaningful if the relation has no on-disk file.)|
+|`relpages`|int4| |Size of the on-disk representation of this table in pages (of size `BLCKSZ`). This is only an estimate used by the planner. It is updated by `VACUUM`, `ANALYZE`, and a few DDL commands such as `CREATE INDEX`.|
+|`reltuples`|float4| |Number of rows in the table. This is only an estimate used by the planner. It is updated by `VACUUM`, `ANALYZE`, and a few DDL commands such as `CREATE INDEX`.|
+|`relallvisible`|int4| |Number of pages that are marked all-visible in the table's visibility map. This is only an estimate used by the planner. It is updated by `VACUUM`, `ANALYZE`, and a few DDL commands such as `CREATE INDEX`.|
+|`reltoastrelid`|oid| `pg_class.oid` |The object identifier of the TOAST table associated with this table, `0` if none. The TOAST table stores large attributes "out of line" in a secondary table.|
+|`relhasindex`|boolean| |True if this is a table and it has (or recently had) any indexes. |
+|`relisshared`|boolean| |True if this table is shared across all databases in the system. Only certain system catalog tables (such as `pg_database`) are shared.|
+|`relpersistence`|char| |The type of object persistence: `p` = heap or append-optimized permanent table, `u` = unlogged temporary table, `t` = temporary table.|
+|`relkind`|char| |The type of object<br/><br/>`r` = heap or append-optimized ordinary table, `i` = index, `S` = sequence, `t` = TOAST table, `v` = view, `m` = materialized view, `c` = composite type, `f` = foreign table, `p` = partitioned table, `I` = partitioned index, `u` = uncatalogued temporary heap table, `o` = internal append-optimized segment files and EOFs, `b` = append-only block directory, `M` = append-only visibility map.|
+|`relnatts`|int2| |Number of user columns in the relation (system columns not counted). There must be this many corresponding entries in `pg_attribute`. See also `pg_attribute.attnum`.|
+|`relchecks`|int2| |Number of `CHECK` constraints on the table; see `pg_constraint` catalog.|
+|`relhasrules`|boolean| |True if table has (or once had) rules; see `pg_rewrite` catalog.|
+|`relhastriggers`|boolean| |True if table has (or once had) triggers.|
+|`relhassubclass`|boolean| |True if table has (or once had) any inheritance children.|
+|`relrowsecurity`|boolean| |True if table has row level security enabled; see `pg_policy` catalog.|
+|`relforcerowsecurity`|boolean| |True if row level security (when enabled) will also apply to the table owner; see `pg_policy` catalog.|
+|`relispopulated`|boolean| |True if relation is populated (this is true for all relations other than some materialized views).|
+|`relreplident`|char| |Columns used to form "replica identity" for rows: `d` = default (primary key, if any), `n` = nothing, `f` = all columns, `i` = index with `indisreplident` set (same as nothing if the index used has been dropped).|
+|`relispartition`|boolean| | True if table or index is a partition.|
+|`relrewrite`|oid|`pg_class.oid` | For new relations being written during a DDL operation that requires a table rewrite, this contains the object identifier of the original relation; otherwise 0. That state is only visible internally; this field should never contain anything other than 0 for a user-visible relation.|
+|`relfrozenxid`|xid| |All transaction IDs before this one have been replaced with a permanent (frozen) transaction ID in this table. This is used to track whether the table needs to be vacuumed in order to prevent transaction ID wraparound or to allow `pg_xact` to be shrunk.<br/><br/>The value is `0` (`InvalidTransactionId`) if the relation is not a table or if the table does not require vacuuming to prevent transaction ID wraparound. The table still might require vacuuming to reclaim disk space.|
+|`relminmxid`|xid| |All multixact IDs before this one have been replaced by a transaction ID in this table. This is used to track whether the table needs to be vacuumed in order to prevent multixact ID wraparound or to allow `pg_multixact` to be shrunk. Zero (`InvalidMultiXactId`) if the relation is not a table.|
+|`relacl`|aclitem[]| |Access privileges assigned by `GRANT` and `REVOKE`.|
+|`reloptions`|text[]| |Access-method-specific options, as "keyword=value" strings.|
+|`relpartbound`|`pg_node_tree`| |If table is a partition (see `relispartition`), internal representation of the partition bound.|
+
+Several of the Boolean flags in `pg_class` are maintained lazily: they are guaranteed to be true if that's the correct state, but might not be reset to false immediately when the condition is no longer true. For example, `relhasindex` is set by `CREATE INDEX`, but it is never cleared by `DROP INDEX`. Instead, `VACUUM` clears `relhasindex` if it finds the table has no indexes. This arrangement avoids race conditions and improves concurrency.

docs/sys-catalogs/sys-tables/sys-tbl-pg-constraint.md

@@ -0,0 +1,6 @@
+---
+title: pg_constraint
+---
+
+# pg_constraint
+