nocodb

The nocodb object gives scripts access to the NocoDB API v3 and to the content of attachment files. You do not need an API token: the script runs as the user who runs it.

Methods

requestAsync

Calls the NocoDB API v3 of the current project as the user who runs the script. Use it for API features that the script objects do not have.

Parameters:

  • request (Object):
    • method ('GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', optional): Default GET.
    • path (string): Must start with /api/v3/data/{projectId}/ or /api/v3/meta/bases/{projectId}/, for the current project.
    • query (Object, optional): Query parameters
    • body (optional): The request body

Returns: Promise<{status: number, data: any}>

Example:

const table = base.getTable('Orders');

const res = await nocodb.requestAsync({
  path: `/api/v3/data/${base.id}/${table.id}/records`,
  query: { pageSize: 5 }
});
output.inspect(res.data);

readAttachmentAsync

Downloads one file of an Attachment cell.

Parameters:

  • attachment (Object): One entry of the array that record.getCellValue() returns for an Attachment field

Returns: Promise<{bytes: Uint8Array, filename: string, contentType: string, size: number}>

Note: Files that NocoDB stores on the local disk of a self-hosted instance can be read only in the script editor. Files in cloud storage, for example S3, can be read in every kind of script.

Example:

const invoices = base.getTable('Invoices');
const invoice = await invoices.selectRecordAsync('42');
const [pdf] = invoice.getCellValue('PDF') ?? [];

if (pdf) {
  const { bytes, filename, size } = await nocodb.readAttachmentAsync(pdf);
  output.text(`${filename}: ${size} bytes`);

  // Attach the same file to another record
  await invoices.uploadAttachmentAsync('43', 'PDF', bytes, { filename });
}

Errors

Every table, view, record, field and nocodb method throws a NocoDBError when it fails. A NocoDBError is an Error, so message is available as before. It has these properties:

PropertyTypeDescription
messagestringWhat failed, for example Failed to update record 1 in table Tasks: <reason>
operationstringThe method that failed, for example table.updateRecordAsync
tableNamestringThe table, if there is one
statusnumberThe HTTP status of the failed request, if there was a request
codestringThe NocoDB error code, for example ERR_RECORD_NOT_FOUND
details.completedIdsArray<string>For a batch write that failed after some requests: the records already written
causeunknownThe original error

NocoDB retries reads (selects, counts, linked records and file downloads) two times after a network error or an HTTP status of 502, 503 or 504. NocoDB does not retry writes.

Example:

const tasksTable = base.getTable('Tasks');

try {
  await tasksTable.updateRecordsAsync(changes);
} catch (e) {
  if (e instanceof NocoDBError) {
    output.text(`${e.operation} failed with ${e.status} ${e.code ?? ''}`);
    output.text(`Already saved: ${(e.details?.completedIds ?? []).join(', ')}`);
  } else {
    throw e;
  }
}

Last updated on

Latest product updates?See Changelog
Stay in the loop? Follow us onLinkedInLinkedInYouTubeYouTubeXX