# Namespaces ## List namespaces in catalog `client.r2DataCatalog.namespaces.list(stringbucketName, NamespaceListParamsparams, RequestOptionsoptions?): NamespaceListResponse` **get** `/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces` Returns a list of namespaces in the specified R2 catalog. Supports hierarchical filtering and pagination for efficient traversal of large namespace hierarchies. ### Parameters - `bucketName: string` Specifies the R2 bucket name. - `params: NamespaceListParams` - `account_id: string` Path param: Use this to identify the account. - `page_size?: number` Query param: Maximum number of namespaces to return per page. Defaults to 100, maximum 1000. - `page_token?: string` Query param: Opaque pagination token from a previous response. Use this to fetch the next page of results. - `parent?: string` Query param: Parent namespace to filter by. Only returns direct children of this namespace. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics"). Omit this parameter to list top-level namespaces. - `return_details?: boolean` Query param: Whether to include additional metadata (timestamps). When true, response includes created_at and updated_at arrays. - `return_uuids?: boolean` Query param: Whether to include namespace UUIDs in the response. Set to true to receive the namespace_uuids array. ### Returns - `NamespaceListResponse` Contains the list of namespaces with optional pagination. - `namespaces: Array>` Lists namespaces in the catalog. - `details?: Array | null` Contains detailed metadata for each namespace when return_details is true. Each object includes the namespace, UUID, and timestamps. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `namespace_uuid: string` Contains the UUID that persists across renames. - `created_at?: string | null` Indicates the creation timestamp in ISO 8601 format. - `updated_at?: string | null` Shows the last update timestamp in ISO 8601 format. Null if never updated. - `namespace_uuids?: Array | null` Contains UUIDs for each namespace when return_uuids is true. The order corresponds to the namespaces array. - `next_page_token?: string | null` Use this opaque token to fetch the next page of results. A null or absent value indicates the last page. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const namespaces = await client.r2DataCatalog.namespaces.list('my-data-bucket', { account_id: '0123456789abcdef0123456789abcdef', }); console.log(namespaces.namespace_uuids); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": { "namespaces": [ [ "bronze", "analytics" ] ], "details": [ { "namespace": [ "bronze", "analytics" ], "namespace_uuid": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "created_at": "2019-12-27T18:11:19.117Z", "updated_at": "2019-12-27T18:11:19.117Z" } ], "namespace_uuids": [ "0199b999-6869-7383-bb1f-d30e059d5326", "0199b99b-2c88-73b3-8dbb-421e0e8f2757" ], "next_page_token": "MSYxNzU5NzU1NTc4NTA0MTk0JjAxOTliOTliLTJjODgtNzNiMy04ZGJiLTQyMWUwZThmMjc1Nw" } } ``` ## Domain Types ### Namespace List Response - `NamespaceListResponse` Contains the list of namespaces with optional pagination. - `namespaces: Array>` Lists namespaces in the catalog. - `details?: Array | null` Contains detailed metadata for each namespace when return_details is true. Each object includes the namespace, UUID, and timestamps. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `namespace_uuid: string` Contains the UUID that persists across renames. - `created_at?: string | null` Indicates the creation timestamp in ISO 8601 format. - `updated_at?: string | null` Shows the last update timestamp in ISO 8601 format. Null if never updated. - `namespace_uuids?: Array | null` Contains UUIDs for each namespace when return_uuids is true. The order corresponds to the namespaces array. - `next_page_token?: string | null` Use this opaque token to fetch the next page of results. A null or absent value indicates the last page. # Tables ## List tables in namespace `client.r2DataCatalog.namespaces.tables.list(stringbucketName, stringnamespace, TableListParamsparams, RequestOptionsoptions?): TableListResponse` **get** `/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables` Returns a list of tables in the specified namespace within an R2 catalog. Supports pagination for efficient traversal of large table collections. ### Parameters - `bucketName: string` Specifies the R2 bucket name. - `namespace: string` - `params: TableListParams` - `account_id: string` Path param: Use this to identify the account. - `page_size?: number` Query param: Maximum number of tables to return per page. Defaults to 100, maximum 1000. - `page_token?: string` Query param: Opaque pagination token from a previous response. Use this to fetch the next page of results. - `return_details?: boolean` Query param: Whether to include additional metadata (timestamps, locations). When true, response includes created_at, updated_at, metadata_locations, and locations arrays. - `return_uuids?: boolean` Query param: Whether to include table UUIDs in the response. Set to true to receive the table_uuids array. ### Returns - `TableListResponse` Contains the list of tables with optional pagination. - `identifiers: Array` Lists tables in the namespace. - `name: string` Specifies the table name. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `details?: Array | null` Contains detailed metadata for each table when return_details is true. Each object includes identifier, UUID, timestamps, and locations. - `identifier: Identifier` Specifies a unique table identifier within a catalog. - `name: string` Specifies the table name. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `table_uuid: string` Contains the UUID that persists across renames. - `created_at?: string | null` Indicates the creation timestamp in ISO 8601 format. - `location?: string | null` Specifies the base S3 URI for table storage location. - `metadata_location?: string | null` Contains the S3 URI to table metadata file. Null for staged tables. - `updated_at?: string | null` Shows the last update timestamp in ISO 8601 format. Null if never updated. - `next_page_token?: string | null` Use this opaque token to fetch the next page of results. A null or absent value indicates the last page. - `table_uuids?: Array | null` Contains UUIDs for each table when return_uuids is true. The order corresponds to the identifiers array. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const tables = await client.r2DataCatalog.namespaces.tables.list('my-data-bucket', 'bronze', { account_id: '0123456789abcdef0123456789abcdef', }); console.log(tables.identifiers); ``` #### Response ```json { "errors": [], "messages": [], "result": { "details": [ { "created_at": "2025-10-07T10:00:00Z", "identifier": { "name": "events", "namespace": [ "bronze" ] }, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/", "metadata_location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/metadata/v1.metadata.json", "table_uuid": "0199b9a1-28a0-71e0-a73e-b0fc32c8468e", "updated_at": "2025-10-07T15:00:00Z" }, { "created_at": "2025-10-07T10:30:00Z", "identifier": { "name": "users", "namespace": [ "bronze" ] }, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id-2/", "metadata_location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id-2/metadata/v2.metadata.json", "table_uuid": "0199b9a1-3c74-7731-bf53-d8c67ead079d", "updated_at": "2025-10-07T16:00:00Z" } ], "identifiers": [ { "name": "events", "namespace": [ "bronze" ] }, { "name": "users", "namespace": [ "bronze" ] } ], "next_page_token": null, "table_uuids": [ "0199b9a1-28a0-71e0-a73e-b0fc32c8468e", "0199b9a1-3c74-7731-bf53-d8c67ead079d" ] }, "success": true } ``` ## Domain Types ### Table List Response - `TableListResponse` Contains the list of tables with optional pagination. - `identifiers: Array` Lists tables in the namespace. - `name: string` Specifies the table name. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `details?: Array | null` Contains detailed metadata for each table when return_details is true. Each object includes identifier, UUID, timestamps, and locations. - `identifier: Identifier` Specifies a unique table identifier within a catalog. - `name: string` Specifies the table name. - `namespace: Array` Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics". - `table_uuid: string` Contains the UUID that persists across renames. - `created_at?: string | null` Indicates the creation timestamp in ISO 8601 format. - `location?: string | null` Specifies the base S3 URI for table storage location. - `metadata_location?: string | null` Contains the S3 URI to table metadata file. Null for staged tables. - `updated_at?: string | null` Shows the last update timestamp in ISO 8601 format. Null if never updated. - `next_page_token?: string | null` Use this opaque token to fetch the next page of results. A null or absent value indicates the last page. - `table_uuids?: Array | null` Contains UUIDs for each table when return_uuids is true. The order corresponds to the identifiers array. # Maintenance Configs ## Get table maintenance configuration `client.r2DataCatalog.namespaces.tables.maintenanceConfigs.get(stringbucketName, stringnamespace, stringtableName, MaintenanceConfigGetParamsparams, RequestOptionsoptions?): MaintenanceConfigGetResponse` **get** `/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs` Retrieve the maintenance configuration for a specific table, including compaction settings. ### Parameters - `bucketName: string` Specifies the R2 bucket name. - `namespace: string` - `tableName: string` - `params: MaintenanceConfigGetParams` - `account_id: string` Use this to identify the account. ### Returns - `MaintenanceConfigGetResponse` Contains table maintenance configuration. - `maintenance_config: MaintenanceConfig` Configures maintenance for the table. - `compaction?: Compaction` Configures compaction settings for table optimization. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` - `target_size_mb: "64" | "128" | "256" | "512"` Sets the target file size for compaction in megabytes. Defaults to "128". - `"64"` - `"128"` - `"256"` - `"512"` - `snapshot_expiration?: SnapshotExpiration` Configures snapshot expiration settings. - `max_snapshot_age: string` Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d". - `min_snapshots_to_keep: number` Specifies the minimum number of snapshots to retain. Defaults to 100. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const maintenanceConfig = await client.r2DataCatalog.namespaces.tables.maintenanceConfigs.get( 'my-data-bucket', 'my_namespace%1Fsub_namespace', 'my_table', { account_id: '0123456789abcdef0123456789abcdef' }, ); console.log(maintenanceConfig.maintenance_config); ``` #### Response ```json { "errors": [], "messages": [], "result": { "maintenance_config": { "compaction": { "state": "enabled", "target_size_mb": "128" }, "snapshot_expiration": { "max_snapshot_age": "7d", "min_snapshots_to_keep": 100, "state": "enabled" } } }, "success": true } ``` ## Update table maintenance configuration `client.r2DataCatalog.namespaces.tables.maintenanceConfigs.update(stringbucketName, stringnamespace, stringtableName, MaintenanceConfigUpdateParamsparams, RequestOptionsoptions?): MaintenanceConfigUpdateResponse` **post** `/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs` Update the maintenance configuration for a specific table. This allows you to enable or disable compaction and adjust target file sizes for optimization. ### Parameters - `bucketName: string` Specifies the R2 bucket name. - `namespace: string` - `tableName: string` - `params: MaintenanceConfigUpdateParams` - `account_id: string` Path param: Use this to identify the account. - `compaction?: Compaction` Body param: Updates compaction configuration (all fields optional). - `state?: "enabled" | "disabled"` Updates the state optionally. - `"enabled"` - `"disabled"` - `target_size_mb?: "64" | "128" | "256" | "512"` Updates the target file size optionally. - `"64"` - `"128"` - `"256"` - `"512"` - `snapshot_expiration?: SnapshotExpiration` Body param: Updates snapshot expiration configuration (all fields optional). - `max_snapshot_age?: string` Updates the maximum age for snapshots optionally. - `min_snapshots_to_keep?: number` Updates the minimum number of snapshots to retain optionally. - `state?: "enabled" | "disabled"` Updates the state optionally. - `"enabled"` - `"disabled"` ### Returns - `MaintenanceConfigUpdateResponse` Configures maintenance for the table. - `compaction?: Compaction` Configures compaction settings for table optimization. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` - `target_size_mb: "64" | "128" | "256" | "512"` Sets the target file size for compaction in megabytes. Defaults to "128". - `"64"` - `"128"` - `"256"` - `"512"` - `snapshot_expiration?: SnapshotExpiration` Configures snapshot expiration settings. - `max_snapshot_age: string` Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d". - `min_snapshots_to_keep: number` Specifies the minimum number of snapshots to retain. Defaults to 100. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const maintenanceConfig = await client.r2DataCatalog.namespaces.tables.maintenanceConfigs.update( 'my-data-bucket', 'my_namespace%1Fsub_namespace', 'my_table', { account_id: '0123456789abcdef0123456789abcdef', compaction: { state: 'enabled', target_size_mb: '256' }, snapshot_expiration: { max_snapshot_age: '14d', min_snapshots_to_keep: 5, state: 'enabled', }, }, ); console.log(maintenanceConfig.compaction); ``` #### Response ```json { "errors": [], "messages": [], "result": { "compaction": { "state": "enabled", "target_size_mb": "256" }, "snapshot_expiration": { "max_snapshot_age": "14d", "min_snapshots_to_keep": 5, "state": "enabled" } }, "success": true } ``` ## Domain Types ### Maintenance Config Get Response - `MaintenanceConfigGetResponse` Contains table maintenance configuration. - `maintenance_config: MaintenanceConfig` Configures maintenance for the table. - `compaction?: Compaction` Configures compaction settings for table optimization. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` - `target_size_mb: "64" | "128" | "256" | "512"` Sets the target file size for compaction in megabytes. Defaults to "128". - `"64"` - `"128"` - `"256"` - `"512"` - `snapshot_expiration?: SnapshotExpiration` Configures snapshot expiration settings. - `max_snapshot_age: string` Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d". - `min_snapshots_to_keep: number` Specifies the minimum number of snapshots to retain. Defaults to 100. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` ### Maintenance Config Update Response - `MaintenanceConfigUpdateResponse` Configures maintenance for the table. - `compaction?: Compaction` Configures compaction settings for table optimization. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"` - `target_size_mb: "64" | "128" | "256" | "512"` Sets the target file size for compaction in megabytes. Defaults to "128". - `"64"` - `"128"` - `"256"` - `"512"` - `snapshot_expiration?: SnapshotExpiration` Configures snapshot expiration settings. - `max_snapshot_age: string` Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d". - `min_snapshots_to_keep: number` Specifies the minimum number of snapshots to retain. Defaults to 100. - `state: "enabled" | "disabled"` Specifies the state of maintenance operations. - `"enabled"` - `"disabled"`