swagger: '2.0' info: description: >- DATA Tables API version: "5.0" title: DATA Tables license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' basePath: /index.php/api/ tags: - name: Table Management description: Create, read, update, delete, and export table definitions - name: Data Dictionary description: Manage field definitions and metadata - name: Data Operations description: Query and insert table data - name: Data Import description: Upload and import CSV data files - name: Indexes description: Manage database indexes for performance - name: Study Integration description: Attach and manage tables within studies x-tagGroups: - name: Table Management tags: - Table Management - name: Data Dictionary tags: - Data Dictionary - name: Data Operations tags: - Data Operations - Data Import - name: Performance tags: - Indexes - name: Integration tags: - Study Integration schemes: - http - https paths: /tables: get: tags: - Table Management summary: List all tables description: Returns a paginated list of all tables. Only returns tables that have both db_id and table_id fields. operationId: listTables consumes: - application/json produces: - application/json parameters: - in: "query" name: "limit" type: integer description: "Number of tables to return (default: 15, max: 100)" minimum: 1 maximum: 100 default: 15 required: false - in: "query" name: "offset" type: integer description: "Number of tables to skip for pagination (default: 0)" minimum: 0 default: 0 required: false responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" tables: type: object description: "Object with table_id as keys" additionalProperties: type: object properties: _id: type: string description: "Table identifier" db_id: type: string description: "Database ID" table_id: type: string description: "Table ID" title: type: string description: "Table title" description: type: string description: "Table description" rows_count: type: integer description: "Number of rows in the table" storage_size: type: string description: "Storage size (e.g., '86M')" nindexes: type: integer description: "Number of indexes" created_at: type: string format: date-time description: "Creation timestamp" updated_at: type: string format: date-time description: "Last update timestamp" total: type: integer description: "Total number of tables (before pagination)" limit: type: integer description: "Limit used" offset: type: integer description: "Offset used" count: type: integer description: "Number of tables in current page" security: - ApiKeyAuth: [] /tables/info/{dbId}/{tableId}: get: tags: - Table Management summary: Get table info description: Returns table definition operationId: tableInfo consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " responses: '200': description: successful operation schema: $ref: "#/definitions/TableInfoResponse" security: - ApiKeyAuth: [] /tables/data/{dbId}/{tableId}: get: tags: - Data Operations summary: Get table data description: Get table data operationId: getTableData consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " - in: "query" name: "limit" type: integer description: "Number of rows to return (default: 100, max: 10000)" minimum: 1 maximum: 10000 default: 100 required: false - in: "query" name: "offset" type: integer description: "Number of rows to skip for pagination (default: 0)" minimum: 0 default: 0 required: false - in: "query" name: "c[field_name]" type: string description: | Filter by field value(s). Use c[field_name] format to avoid conflicts with reserved parameters. Supported formats: - Range: c[age]=1-12 (values between 1 and 12) - Multiple values: c[sex]=1,2,3 (any of these values) - Combined: c[age]=1-12,24-30,7,9 (range and individual values) - Greater than: c[age]=>10 (values >= 10) - Less than: c[age]=<10 (values <= 10) - Exclusion: c[sex]=!5 (exclude value 5) - Quoted strings: c[name]="John Doe" (exact string match) required: false - in: "query" name: "fields" type: string description: A comma separated list of fields to output. If not specified, all fields are returned. required: false - in: "query" name: "format" type: string description: Output format - json (default) or csv required: false - in: "query" name: "debug" type: boolean description: Include debug information (options, features, filters) in response required: false responses: '200': description: successful operation security: - ApiKeyAuth: [] /tables/create_table/{dbId}/{tableId}: post: tags: - Table Management summary: Create new table description: Create new table with metadata and optionally field definitions. operationId: createTableType consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "body" name: "body" required: false schema: type: object properties: title: type: string description: Table title description: type: string description: Table description data_dictionary: type: array description: Array of field definitions items: type: object properties: name: type: string description: Field name label: type: string description: Field label description: type: string description: Field description data_type: type: string description: Data type (string, integer, float, double, date, boolean, datetime, array, object, null) column_type: type: string description: Column type (dimension, time_period, measure, attribute, indicator_id, indicator_name, geography, observation_value, periodicity) time_period_format: type: string description: Time period format (e.g., YYYY, YYYY-MM) code_list: type: array description: Inline code list items: type: object properties: code: oneOf: - type: string - type: number description: Code value label: type: string description: Code label description: type: string description: Code description code_list_reference: type: object description: External code list reference properties: id: type: string description: Code list ID name: type: string description: Code list name version: type: string description: Code list version uri: type: string description: Code list URI note: type: string description: Additional notes responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" result: type: integer description: "Number of documents inserted (should be 1)" fields_created: type: integer description: "Number of field definitions created" message: type: string example: "Table created with 5 field(s)" '400': description: "Validation error" schema: type: object properties: status: type: string example: "failed" message: type: string examples: invalid_db_id: "Invalid db_id: Only alphanumeric characters and underscores are allowed" invalid_table_id: "Invalid table_id: Only alphanumeric characters and underscores are allowed" security: - ApiKeyAuth: [] /tables/upload/{dbId}/{tableId}: post: tags: - Data Import summary: Upload CSV file description: | Upload CSV or ZIP file and create/update table definition. This is the first step in the import workflow; use `/import` to process data into the database. **Direct upload:** multipart/form-data with field `file` (small files). **Large / resumable upload:** 1. `POST /api/uploads/init` with filename, total_size, total_chunks, chunk_size 2. `POST /api/uploads/chunk/{upload_id}` for each chunk (resume via `GET /api/uploads/status/{upload_id}`) 3. `POST /tables/upload/{dbId}/{tableId}` with JSON body `{ "upload_id": "" }` Provide either `file` or `upload_id`, not both. For ZIP files, the CSV must match the ZIP filename (e.g. `data.zip` → `data.csv`). operationId: uploadCsv consumes: - multipart/form-data - application/json produces: - application/json parameters: - in: "path" name: "dbId" description: "Database ID " type: string required: true - in: "path" name: "tableId" description: "Table ID " type: string required: true - in: "formData" name: "file" type: file description: "CSV or ZIP file (multipart only). Omit when using upload_id." required: false - in: "formData" name: "upload_id" type: string description: "Completed resumable upload id from /api/uploads (alternative to file)." required: false - in: "formData" name: "title" type: string description: "Table title" required: false - in: "formData" name: "description" type: string description: "Table description" required: false - in: "body" name: "body" description: "JSON alternative to form fields (upload_id, title, description)" required: false schema: type: object properties: upload_id: type: string description: "Completed resumable upload id from POST /api/uploads/*" title: type: string description: type: string responses: '200': description: successful operation schema: $ref: "#/definitions/UploadResponse" '400': description: "Upload error" schema: type: object properties: status: type: string example: "failed" message: type: string examples: zip_extraction_failed: "Failed to unzip file: filename.zip" csv_not_found: "CSV file not found in ZIP" file_upload_failed: "File upload failed" security: - ApiKeyAuth: [] /tables/import/{dbId}/{tableId}: post: tags: - Data Import summary: Import CSV data description: Import CSV data in chunks for large files. Requires that a file has been uploaded using the `/upload` endpoint first. Automatically resumes from last byte position. Use `status=true` to check import progress without processing data. operationId: importCsv consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" description: "Database ID " type: string required: true - in: "path" name: "tableId" description: "Table ID " type: string required: true - in: "body" name: "body" description: "Import parameters" required: false schema: type: object properties: status: type: boolean description: "If true, returns only import status without processing data (default: false)" default: false max_time: type: integer description: "Maximum execution time in seconds (default: 30, min: 10, max: 120). Processes as many rows as possible within this time." minimum: 10 maximum: 120 default: 30 delimiter: type: string description: "CSV delimiter - comma, tab, semicolon (default: comma)" enum: ["comma", "tab", "semicolon", ",", ";"] default: "comma" responses: '200': description: successful operation schema: $ref: "#/definitions/ImportResponse" '400': description: "Validation error - table has data or data inconsistency" schema: type: object properties: status: type: string example: "failed" message: type: string example: "Table already contains 1000 rows. Use DELETE /api/tables/{dbId}/{tableId} to clear data first." action_required: type: string enum: ["delete_data_first", "reset_import"] description: "Action to take to resolve the error" security: - ApiKeyAuth: [] /tables/update_table/{dbId}/{tableId}: put: tags: - Table Management summary: Update table metadata description: Update table metadata (title, description). operationId: updateTable consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "body" name: "body" required: true schema: type: object properties: title: type: string description: "Table title" description: type: string description: "Table description" responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" message: type: string example: "Table information updated successfully" modified_count: type: integer description: "Number of documents modified" security: - ApiKeyAuth: [] /tables/{dbId}/{tableId}: delete: tags: - Table Management summary: Delete table data description: Delete table data and optionally table definition. operationId: deleteTable consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" description: Database ID type: string required: true - in: "path" name: "tableId" description: Table ID type: string required: true - in: "body" name: "body" description: "Delete options" required: false schema: type: object properties: delete_definition: type: boolean description: "Delete table definition, fields, and data (default: false)" default: false responses: '200': description: successful operation schema: $ref: "#/definitions/DeleteResponse" security: - ApiKeyAuth: [] /tables/insert/{dbId}/{tableId}: post: tags: - Data Operations summary: Insert table data description: Insert rows of data as JSON object operationId: postTable consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " - in: "body" name: "body" description: "Table rows as JSON object" required: true schema: type: object responses: '200': description: successful operation security: - ApiKeyAuth: [] /tables/indexes/{dbId}/{tableId}: get: tags: - Indexes summary: Get table indexes description: Returns a list of table indexes operationId: tableIndexes consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " responses: '200': description: successful operation security: - ApiKeyAuth: [] post: tags: - Indexes summary: Create table index description: Create a new index operationId: tableIndex consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " - in: body name: index_fields description: A comma seperated list of fields for creating new index e.g. `state, district, urbrur` schema: type: object required: - index_fields properties: index_fields: type: string responses: '200': description: successful operation security: - ApiKeyAuth: [] delete: tags: - Indexes summary: Delete table index description: Delete a table index - `tables/indexes/{dbId}/{tableId}/{indexName}` operationId: tableIndexesDelete consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " - in: "path" name: "indexName" type: string format: string required: true responses: '200': description: successful operation security: - ApiKeyAuth: [] /tables/text_index/{dbId}/{tableId}: post: tags: - Indexes summary: Create fulltext index description: Create a fulltext index for table. Only one text index can be created per table. operationId: tableTextIndex consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string format: string required: true description: "Database ID " - in: "path" name: "tableId" type: string format: string required: true description: "Table ID " - in: body name: index_fields description: A comma seperated list of fields for creating new index e.g. `state, district, urbrur` schema: type: object required: - index_fields properties: index_fields: type: string responses: '200': description: successful operation security: - ApiKeyAuth: [] /tables/attach_to_study: post: tags: - Study Integration summary: Attach table to a study description: Attach a table to a study. Accepts either 'idno' (study IDNO) or 'sid' (study ID). operationId: tableAttachToStudy consumes: - application/json produces: - application/json parameters: - in: body schema: type: object required: - db_id - table_id properties: db_id: type: string description: "Database ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" table_id: type: string description: "Table ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" idno: type: string description: "Study IDNO (unique identifier). Either 'idno' or 'sid' must be provided." example: "ZMB_2001_DHS_v01_M_v02_A_IPUMS" sid: type: integer description: "Study ID (internal ID). Either 'idno' or 'sid' must be provided." example: 452 responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" result: type: boolean description: "True if attachment was successful or already exists" '400': description: Bad request schema: type: object properties: status: type: string example: "failed" error: type: string example: "Missing Param:: idno or sid" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}: get: tags: - Data Dictionary summary: Get all fields for a table description: Returns all field definitions (data dictionary) for a table. Fields are sorted by field_order. operationId: getTableFields consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" db_id: type: string table_id: type: string total_fields: type: integer description: "Total number of fields" fields: type: array description: "Array of field definitions" items: $ref: "#/definitions/FieldDefinition" security: - ApiKeyAuth: [] post: tags: - Data Dictionary summary: Create or update field (upsert) description: Create a new field or update an existing field. If field exists, it will be updated. If not, it will be created. operationId: upsertField consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "body" name: "body" required: true schema: $ref: "#/definitions/FieldDefinition" responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" field: $ref: "#/definitions/FieldDefinition" action: type: string enum: ["created", "updated"] description: "Whether field was created or updated" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}/{fieldName}: get: tags: - Data Dictionary summary: Get single field definition description: Returns a single field definition by field name. operationId: getField consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "path" name: "fieldName" type: string required: true description: "Field name" responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" field: $ref: "#/definitions/FieldDefinition" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}/{fieldName}/delete: post: tags: - Data Dictionary summary: Delete field definition description: Delete a field definition from the data dictionary. POST alias for DELETE method. operationId: deleteField consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "path" name: "fieldName" type: string required: true description: "Field name to delete" responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" message: type: string example: "Field deleted successfully" deleted_count: type: integer description: "Number of fields deleted (should be 1)" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}/populate: post: tags: - Data Dictionary summary: Populate fields from data description: Automatically create field definitions by analyzing actual data in the table. Creates default metadata for each field found in the data. operationId: populateFields consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" db_id: type: string table_id: type: string total_fields: type: integer description: "Total number of fields created/updated" message: type: string example: "Table schema populated successfully" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}/reorder: post: tags: - Data Dictionary summary: Reorder fields description: Update the display order of fields in the data dictionary. operationId: reorderFields consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " - in: "body" name: "body" required: true schema: type: object description: "Object with field names as keys and order numbers as values" additionalProperties: type: integer description: "Field order number" example: ISO3: 1 country: 2 value: 3 responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" updated: type: integer description: "Number of fields updated" security: - ApiKeyAuth: [] /tables/fields/{dbId}/{tableId}/sync: post: tags: - Data Dictionary summary: Sync fields with data description: Synchronize field definitions with actual data. Removes fields that don't exist in the data and adds new fields found in the data. operationId: syncFields consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" fields_removed: type: integer description: "Number of fields removed (not in data)" fields_added: type: integer description: "Number of new fields added (found in data)" message: type: string example: "Fields synced: 2 removed, 3 added" security: - ApiKeyAuth: [] /tables/export_definition/{dbId}/{tableId}: get: tags: - Table Management summary: Export table definition description: Export complete table definition including metadata and all field definitions as JSON. Downloads as a file. operationId: exportTableDefinition consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID " - in: "path" name: "tableId" type: string required: true description: "Table ID " responses: '200': description: successful operation - JSON file download schema: type: object properties: status: type: string example: "success" definition: type: object properties: version: type: string example: "1.0" exported_at: type: string format: date-time table_metadata: type: object properties: db_id: type: string table_id: type: string title: type: string description: type: string created_at: type: string format: date-time updated_at: type: string format: date-time fields: type: array items: $ref: "#/definitions/FieldDefinition" indexes: type: object description: "Collection indexes" security: - ApiKeyAuth: [] /tables/detach_from_study: post: tags: - Study Integration summary: Detach table from study description: Remove the link between a table and a study. The table and study data are not deleted, only the relationship is removed. operationId: tableDetachFromStudy consumes: - application/json produces: - application/json parameters: - in: body schema: type: object required: - db_id - table_id - sid properties: db_id: type: string description: "Database ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" table_id: type: string description: "Table ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" sid: type: integer description: "Study ID (internal ID)" example: 452 responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" result: type: boolean description: "True if detachment was successful" '400': description: Bad request schema: type: object properties: status: type: string example: "failed" error: type: string example: "Missing Param:: sid" security: - ApiKeyAuth: [] /tables/{dbId}/{tableId}/studies: get: tags: - Study Integration summary: Get studies attached to a table description: Returns a list of all studies that are linked to the specified table. operationId: getTableStudies consumes: - application/json produces: - application/json parameters: - in: "path" name: "dbId" type: string required: true description: "Database ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" - in: "path" name: "tableId" type: string required: true description: "Table ID (alphanumeric, underscores only, lowercase)" pattern: "^[a-z0-9_]+$" responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" studies: type: array description: "Array of studies attached to the table" items: type: object properties: id: type: integer description: "Internal record ID" sid: type: integer description: "Study ID" idno: type: string description: "Study IDNO (unique identifier)" example: "ZMB_2001_DHS_v01_M_v02_A_IPUMS" title: type: string description: "Study title" example: "World Health Survey 2003" nation: type: string description: "Country/nation" example: "South Africa" year_start: type: string description: "Start year" example: "2003" db_id: type: string description: "Database ID" table_id: type: string description: "Table ID" total: type: integer description: "Total number of studies attached" example: 1 '400': description: Bad request schema: type: object properties: status: type: string example: "failed" error: type: string example: "Missing Param:: tableId" security: - ApiKeyAuth: [] /tables/list_by_study/{sid}: get: tags: - Study Integration summary: List tables by study description: Get a list of tables attached to a study operationId: tableListByStudy consumes: - application/json produces: - application/json parameters: - in: "path" name: "sid" type: integer description: "Study ID (internal ID)" required: true example: 452 responses: '200': description: successful operation schema: type: object properties: status: type: string example: "success" result: type: array description: "Array of tables attached to the study" items: type: object properties: id: type: integer description: "Internal record ID" sid: type: integer description: "Study ID" db_id: type: string description: "Database ID" table_id: type: string description: "Table ID" title: type: string description: "Dataset title" security: - ApiKeyAuth: [] ############################################################### securityDefinitions: ApiKeyAuth: type: apiKey name: X-API-KEY in: header definitions: CsvImport: type: object properties: db_id: type: string table_id: type: string file_path: type: string description: File name for uploaded CSV file example: "table-name.csv" delimiter: type: string description: CSV delimiter - default is Comma(,) example: "tab" required: - db_id - table_id - file_path xml: name: CsvImport Table: type: object properties: id: type: integer format: int64 readOnly: true table_id: type: string required: true title: "Table unique IDNo" title: type: string required: true description: Table Title description: required: true type: string description: A short description unit_observation: type: string required: true description: Unit of observation features: type: array required: true description: Features items: type: string xml: name: table TableInfoResponse: type: object properties: status: type: string example: "success" result: type: object properties: count: type: integer description: "Total number of rows in the table" metadata: type: object properties: _id: type: string description: "Table definition ID" title: type: string description: "Table title" description: type: string description: "Table description" table_id: type: string description: "Table ID" csv_file_path: type: string description: "Path to CSV file" delimiter: type: string description: "CSV delimiter" created_at: type: string format: date-time updated_at: type: string format: date-time db_id: type: string description: "Database ID" csv_uploaded_at: type: string format: date-time ApiResponse: type: object properties: code: type: integer format: int32 type: type: string message: type: string UploadResponse: type: object properties: status: type: string example: "success" file_path: type: string description: "Partial file path for import" upload_source: type: string enum: ["file", "upload_id"] description: "Whether the file came from direct multipart upload or resumable upload_id" action: type: string enum: ["created", "updated"] csv_uploaded_at: type: string format: date-time import_status: type: string example: "ready" links: type: object properties: import: type: string description: "Import endpoint URL" message: type: string ZipFileRequirements: type: object description: "Requirements for ZIP files containing CSV data" properties: filename_matching: type: string description: "CSV filename must match ZIP filename (without extension)" example: "data.zip must contain data.csv" supported_extensions: type: array items: type: string description: "Supported CSV file extensions" example: [".csv", ".txt", ".CSV", ".TXT"] file_structure: type: string description: "ZIP file structure requirements" example: "ZIP must contain exactly one CSV file at root level" examples: type: object properties: valid: type: object properties: zip_file: type: string example: "report.zip" csv_file: type: string example: "report.csv" invalid: type: object properties: zip_file: type: string example: "data.zip" csv_file: type: string example: "other.csv" reason: type: string example: "Filename mismatch" ImportResponse: type: object properties: status: type: string example: "success" csv_info: type: object properties: csv_file_path: type: string description: "Path to the CSV file being imported" example: "mydb/mytable/data.csv" csv_uploaded_at: type: string format: date-time description: "When the CSV file was uploaded" file_size: type: integer description: "Total file size in bytes" example: 524288000 file_size_mb: type: number format: float description: "Total file size in megabytes" example: 500.0 batch: type: object description: "Information about the current batch processed" properties: rows_processed: type: integer description: "Number of rows processed in this batch" example: 45000 byte_offset_start: type: integer description: "File byte position where this batch started" example: 12500000 byte_offset_end: type: integer description: "File byte position where this batch ended (resume point for next batch)" example: 15750000 execution_time_seconds: type: number format: float description: "Execution time for this batch in seconds" example: 29.8 execution_time_formatted: type: string description: "Human-readable execution time" example: "00h:00m:29s" progress: type: object description: "Overall import progress information" properties: total_rows_processed: type: integer description: "Total cumulative rows imported so far" example: 135000 progress_percent: type: number format: float description: "Import completion percentage (based on file size)" example: 25.5 import_status: type: string enum: ["ready", "in_progress", "completed"] description: "Current import status" has_more: type: boolean description: "Whether there are more batches to process" example: true next: type: object properties: byte_offset: type: integer description: "Byte offset for next batch (resume point)" example: 15750000 endpoint: type: string description: "API endpoint to call for next batch" example: "http://example.com/api/tables/import/mydb/mytable" message: type: string example: "Call this endpoint again to continue import" description: "Only present if has_more is true. Contains information for resuming import." DeleteResponse: type: object properties: status: type: string example: "success" data_deleted: type: integer description: "Number of data rows deleted" definition_deleted: type: integer description: "Number of definitions deleted (0 or 1)" import_progress_reset: type: boolean example: true message: type: string FieldDefinition: type: object description: "Field metadata definition" required: - name properties: name: type: string description: "Field name (required)" label: type: string description: "Field label/display name" description: type: string description: "Field description" data_type: type: string description: "Data type (string, integer, float, double, date, boolean, datetime, array, object, null)" enum: ["string", "integer", "float", "double", "date", "boolean", "datetime", "array", "object", "null"] column_type: type: string description: "Semantic column type" enum: ["dimension", "time_period", "measure", "attribute", "indicator_id", "indicator_name", "geography", "observation_value", "periodicity"] field_order: type: integer description: "Display order of the field" unit_of_measurement: type: string description: "Unit of measurement" format: type: string description: "Format specification" time_period_format: type: string description: "Time period format (e.g., YYYY, YYYY-MM)" code_list: type: array description: "Inline code list values" items: type: object properties: code: oneOf: - type: string - type: number description: "Code value" label: type: string description: "Code label" description: type: string description: "Code description" code_list_reference: type: object description: "External code list reference" properties: id: type: string description: "Code list ID" name: type: string description: "Code list name" version: type: string description: "Code list version" uri: type: string description: "Code list URI" note: type: string description: "Additional notes" created_at: type: string format: date-time description: "Creation timestamp" updated_at: type: string format: date-time description: "Last update timestamp"