Operations reference v7
Reference for pipeline error log functions. For guide-style documentation, see Pipeline error log.
Error log functions
Each pipeline maintains an error log table at {source_schema}.pipeline_{pipeline_name}_errors. These functions provide a consistent interface for querying and managing that log.
aidb.get_error_logs
Returns error log entries for a pipeline, with optional filters.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
pipeline_name | TEXT | Required | Name of the pipeline. |
p_source_id | TEXT | NULL | Filter to a specific source record ID. |
p_pipeline_step | SMALLINT | NULL | Filter to a specific pipeline step number. |
p_error_category | TEXT | NULL | Filter by category: RecordTemporary, RecordPermanent, PipelineTemporary, or PipelinePermanent. |
p_limit | INTEGER | NULL | Maximum number of rows to return. |
p_offset | INTEGER | NULL | Number of rows to skip (for pagination). |
Returns
| Column | Type | Description |
|---|---|---|
id | bigint | Error log entry ID |
source_id | text | Source record that failed |
part_ids | bigint[] | Part identifiers (for chunked records) |
pipeline_step | smallint | Step number where the failure occurred |
step_operation | text | Operation name (for example, ParsePdf, ChunkText) |
error_message | text | Error description |
error_category | aidb.ErrorBlocking | Error category |
failed_at | timestamptz | Timestamp of the failure |
retry_count | integer | Number of retry attempts |
last_retry_at | timestamptz | Timestamp of the last retry |
Examples
-- All errors for a pipeline SELECT * FROM aidb.get_error_logs('my_pipeline'); -- Filter by source record SELECT * FROM aidb.get_error_logs('my_pipeline', p_source_id => 'doc_42'); -- Filter by step and category SELECT * FROM aidb.get_error_logs( 'my_pipeline', p_pipeline_step => 1::smallint, p_error_category => 'RecordPermanent' ); -- Paginate SELECT * FROM aidb.get_error_logs('my_pipeline', p_limit => 20, p_offset => 40);
aidb.get_error_log_summary
Returns aggregated error counts for a single pipeline, grouped by step, operation, and category.
Parameters
| Parameter | Type | Description |
|---|---|---|
pipeline_name | TEXT | Name of the pipeline. |
Returns
| Column | Type | Description |
|---|---|---|
pipeline_step | smallint | Step number |
step_operation | text | Operation name |
error_category | text | Error category |
error_count | bigint | Number of errors in this group |
latest_failed_at | timestamptz | Most recent failure timestamp |
Example
SELECT * FROM aidb.get_error_log_summary('my_pipeline');
Output
pipeline_step | step_operation | error_category | error_count | latest_failed_at
---------------+----------------+-----------------+-------------+----------------------------
1 | ParsePdf | RecordPermanent | 2 | 2026-04-10 14:31:58.456+00
2 | ChunkText | RecordPermanent | 1 | 2026-04-10 14:32:01.123+00
(2 rows)aidb.get_all_error_summaries
Returns the same rollup as aidb.get_error_log_summary() but across all pipelines at once.
Returns
| Column | Type | Description |
|---|---|---|
pipeline_name | text | Pipeline name |
pipeline_step | smallint | Step number |
step_operation | text | Operation name |
error_category | text | Error category |
error_count | bigint | Number of errors in this group |
latest_failed_at | timestamptz | Most recent failure timestamp |
Example
SELECT * FROM aidb.get_all_error_summaries();
Output
pipeline_name | pipeline_step | step_operation | error_category | error_count | latest_failed_at ---------------+---------------+----------------+-------------------+-------------+---------------------------- my_pipeline | 1 | ParsePdf | RecordPermanent | 2 | 2026-04-10 14:31:58.456+00 pdf_ingester | 1 | ParsePdf | PipelinePermanent | 1 | 2026-04-10 15:00:12.000+00 (2 rows)
aidb.clear_error_logs
Deletes specific error log entries by ID. Review entries with aidb.get_error_logs() before clearing.
Parameters
| Parameter | Type | Description |
|---|---|---|
pipeline_name | TEXT | Name of the pipeline. |
error_ids | BIGINT[] | Array of error log entry IDs to delete. |
Returns
INTEGER — the number of rows deleted.
Example
SELECT aidb.clear_error_logs('my_pipeline', ARRAY[1, 3]);
Output
clear_error_logs
------------------
2
(1 row)aidb.retry_pipeline_errors
Note
aidb.retry_pipeline_errors() is not yet available. It will be included in a future release. See Known issues.
Re-processes specific error log entries from the step where they originally failed.
Parameters
| Parameter | Type | Description |
|---|---|---|
pipeline_name | TEXT | Name of the pipeline. |
error_ids | BIGINT[] | Array of error log entry IDs to retry. |
Returns
| Column | Type | Description |
|---|---|---|
error_id | bigint | Error log entry ID |
status | text | resolved or failed |
error_message | text | Failure reason (empty if resolved) |
Resolved entries are removed from the error log. Failed retries remain with an incremented retry_count and updated last_retry_at.
Example
SELECT * FROM aidb.retry_pipeline_errors('my_pipeline', ARRAY[1, 2]);
Output
error_id | status | error_message
----------+----------+----------------------------------
1 | resolved |
2 | failed | failed to extract text from page 0
(2 rows)Error categories
| Category | Scope | Blocks pipeline? | Description |
|---|---|---|---|
RecordTemporary | Single record | No | Transient failure for one record. May succeed on retry. |
RecordPermanent | Single record | No | Permanent failure for one record (for example, corrupt data). |
PipelineTemporary | Entire step | Yes | Transient failure that stopped the step (for example, service outage). May resolve on retry. |
PipelinePermanent | Entire step | Yes | Permanent failure that stopped the step (for example, invalid model config). |
- On this page
- Error log functions
- Error categories