@budibase/server 0.9.190-alpha.7 → 1.0.1

package/src/api/routes/row.js

@@ -14,24 +14,130 @@ const {
 const router = Router()
 
 router
+  /**
+   * @api {get} /api/:tableId/:rowId/enrich Get an enriched row
+   * @apiName Get an enriched row
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This API is only useful when dealing with rows that have relationships.
+   * Normally when a row is a returned from the API relationships will only have the structure
+   * `{ primaryDisplay: "name", _id: ... }` but this call will return the full related rows
+   * for each relationship instead.
+   *
+   * @apiParam {string} rowId The ID of the row which is to be retrieved and enriched.
+   *
+   * @apiSuccess {object} row The response body will be the enriched row.
+   */
   .get(
     "/api/:tableId/:rowId/enrich",
     paramSubResource("tableId", "rowId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.fetchEnrichedRow
   )
+  /**
+   * @api {get} /api/:tableId/rows Get all rows in a table
+   * @apiName Get all rows in a table
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This is a deprecated endpoint that should not be used anymore, instead use the search endpoint.
+   * This endpoint gets all of the rows within the specified table - it is not heavily used
+   * due to its lack of support for pagination. With SQL tables this will retrieve up to a limit and then
+   * will simply stop.
+   *
+   * @apiParam {string} tableId The ID of the table to retrieve all rows within.
+   *
+   * @apiSuccess {object[]} rows The response body will be an array of all rows found.
+   */
   .get(
     "/api/:tableId/rows",
     paramResource("tableId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.fetch
   )
+  /**
+   * @api {get} /api/:tableId/rows/:rowId Retrieve a single row
+   * @apiName Retrieve a single row
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This endpoint retrieves only the specified row. If you wish to retrieve
+   * a row by anything other than its _id field, use the search endpoint.
+   *
+   * @apiParam {string} tableId The ID of the table to retrieve a row from.
+   * @apiParam {string} rowId The ID of the row to retrieve.
+   *
+   * @apiSuccess {object} body The response body will be the row that was found.
+   */
   .get(
     "/api/:tableId/rows/:rowId",
     paramSubResource("tableId", "rowId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.find
   )
+  /**
+   * @api {post} /api/:tableId/search Search for rows in a table
+   * @apiName Search for rows in a table
+   * @apiGroup rows
+   * @apiPermission table read access
+   * @apiDescription This is the primary method of accessing rows in Budibase, the data provider
+   * and data UI in the builder are built atop this. All filtering, sorting and pagination is
+   * handled through this, for internal and external (datasource plus, e.g. SQL) tables.
+   *
+   * @apiParam {string} tableId The ID of the table to retrieve rows from.
+   *
+   * @apiParam (Body) {boolean} [paginate] If pagination is required then this should be set to true,
+   * defaults to false.
+   * @apiParam (Body) {object} [query] This contains a set of filters which should be applied, if none
+   * specified then the request will be unfiltered. An example with all of the possible query
+   * options has been supplied below.
+   * @apiParam (Body) {number} [limit] This sets a limit for the number of rows that will be returned,
+   * this will be implemented at the database level if supported for performance reasons. This
+   * is useful when paginating to set exactly how many rows per page.
+   * @apiParam (Body) {string} [bookmark] If pagination is enabled then a bookmark will be returned
+   * with each successful search request, this should be supplied back to get the next page.
+   * @apiParam (Body) {object} [sort] If sort is desired this should contain the name of the column to
+   * sort on.
+   * @apiParam (Body) {string} [sortOrder] If sort is enabled then this can be either "descending" or
+   * "ascending" as required.
+   * @apiParam (Body) {string} [sortType] If sort is enabled then you must specify the type of search
+   * being used, either "string" or "number". This is only used for internal tables.
+   *
+   * @apiParamExample {json} Example:
+   * {
+   *  "tableId": "ta_70260ff0b85c467ca74364aefc46f26d",
+   *  "query": {
+   *    "string": {},
+   *    "fuzzy": {},
+   *    "range": {
+   *      "columnName": {
+   *        "high": 20,
+   *        "low": 10,
+   *      }
+   *    },
+   *    "equal": {
+   *      "columnName": "someValue"
+   *    },
+   *    "notEqual": {},
+   *    "empty": {},
+   *    "notEmpty": {},
+   *    "contains": {},
+   *    "notContains": {}
+   *    "oneOf": {
+   *      "columnName": ["value"]
+   *    }
+   *  },
+   *  "limit": 10,
+   *  "sort": "name",
+   *  "sortOrder": "descending",
+   *  "sortType": "string",
+   *  "paginate": true
+   * }
+   *
+   * @apiSuccess {object[]} rows An array of rows that was found based on the supplied parameters.
+   * @apiSuccess {boolean} hasNextPage If pagination was enabled then this specifies whether or
+   * not there is another page after this request.
+   * @apiSuccess {string} bookmark The bookmark to be sent with the next request to get the next
+   * page.
+   */
   .post(
     "/api/:tableId/search",
     paramResource("tableId"),
@@ -46,6 +152,30 @@ router
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     rowController.search
   )
+  /**
+   * @api {post} /api/:tableId/rows Creates a new row
+   * @apiName Creates a new row
+   * @apiGroup rows
+   * @apiPermission table write access
+   * @apiDescription This API will create a new row based on the supplied body. If the
+   * body includes an "_id" field then it will update an existing row if the field
+   * links to one. Please note that "_id", "_rev" and "tableId" are fields that are
+   * already used by Budibase tables and cannot be used for columns.
+   *
+   * @apiParam {string} tableId The ID of the table to save a row to.
+   *
+   * @apiParam (Body) {string} [_id] If the row exists already then an ID for the row must be provided.
+   * @apiParam (Body) {string} [_rev] If working with an existing row for an internal table its revision
+   * must also be provided.
+   * @apiParam (Body) {string} tableId The ID of the table should also be specified in the row body itself.
+   * @apiParam (Body) {any} [any] Any field supplied in the body will be assessed to see if it matches
+   * a column in the specified table. All other fields will be dropped and not stored.
+   *
+   * @apiSuccess {string} _id The ID of the row that was just saved, if it was just created this
+   * is the rows new ID.
+   * @apiSuccess {string} [_rev] If saving to an internal table a revision will also be returned.
+   * @apiSuccess {object} body The contents of the row that was saved will be returned as well.
+   */
   .post(
     "/api/:tableId/rows",
     paramResource("tableId"),
@@ -53,18 +183,66 @@ router
     usage,
     rowController.save
   )
+  /**
+   * @api {patch} /api/:tableId/rows Updates a row
+   * @apiName Update a row
+   * @apiGroup rows
+   * @apiPermission table write access
+   * @apiDescription This endpoint is identical to the row creation endpoint but instead it will
+   * error if an _id isn't provided, it will only function for existing rows.
+   */
   .patch(
     "/api/:tableId/rows",
     paramResource("tableId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.WRITE),
     rowController.patch
   )
+  /**
+   * @api {post} /api/:tableId/rows/validate Validate inputs for a row
+   * @apiName Validate inputs for a row
+   * @apiGroup rows
+   * @apiPermission table write access
+   * @apiDescription When attempting to save a row you may want to check if the row is valid
+   * given the table schema, this will iterate through all the constraints on the table and
+   * check if the request body is valid.
+   *
+   * @apiParam {string} tableId The ID of the table the row is to be validated for.
+   *
+   * @apiParam (Body) {any} [any] Any fields provided in the request body will be tested
+   * against the table schema and constraints.
+   *
+   * @apiSuccess {boolean} valid If inputs provided are acceptable within the table schema this
+   * will be true, if it is not then then errors property will be populated.
+   * @apiSuccess {object} [errors] A key value map of information about fields on the input
+   * which do not match the table schema. The key name will be the column names that have breached
+   * the schema.
+   */
   .post(
     "/api/:tableId/rows/validate",
     paramResource("tableId"),
     authorized(PermissionTypes.TABLE, PermissionLevels.WRITE),
     rowController.validate
   )
+  /**
+   * @api {delete} /api/:tableId/rows Delete rows
+   * @apiName Delete rows
+   * @apiGroup rows
+   * @apiPermission table write access
+   * @apiDescription This endpoint can delete a single row, or delete them in a bulk
+   * fashion.
+   *
+   * @apiParam {string} tableId The ID of the table the row is to be deleted from.
+   *
+   * @apiParam (Body) {object[]} [rows] If bulk deletion is desired then provide the rows in this
+   * key of the request body that are to be deleted.
+   * @apiParam (Body) {string} [_id] If deleting a single row then provide its ID in this field.
+   * @apiParam (Body) {string} [_rev] If deleting a single row from an internal table then provide its
+   * revision here.
+   *
+   * @apiSuccess {object[]|object} body If deleting bulk then the response body will be an array
+   * of the deleted rows, if deleting a single row then the body will contain a "row" property which
+   * is the deleted row.
+   */
   .delete(
     "/api/:tableId/rows",
     paramResource("tableId"),

package/src/api/routes/table.js

@@ -27,13 +27,110 @@ function generateSaveValidator() {
 }
 
 router
+  /**
+   * @api {get} /api/tables Fetch all tables
+   * @apiName Fetch all tables
+   * @apiGroup tables
+   * @apiPermission table read access
+   * @apiDescription This endpoint retrieves all of the tables which have been created in
+   * an app. This includes all of the external and internal tables; to tell the difference
+   * between these look for the "type" property on each table, either being "internal" or "external".
+   *
+   * @apiSuccess {object[]} body The response body will be the list of tables that was found - as
+   * this does not take any parameters the only error scenario is no access.
+   */
   .get("/api/tables", authorized(BUILDER), tableController.fetch)
+  /**
+   * @api {get} /api/tables/:id Fetch a single table
+   * @apiName Fetch a single table
+   * @apiGroup tables
+   * @apiPermission table read access
+   * @apiDescription Retrieves a single table this could be be internal or external based on
+   * the provided table ID.
+   *
+   * @apiParam {string} id The ID of the table which is to be retrieved.
+   *
+   * @apiSuccess {object[]} body The response body will be the table that was found.
+   */
   .get(
     "/api/tables/:id",
     paramResource("id"),
     authorized(PermissionTypes.TABLE, PermissionLevels.READ),
     tableController.find
   )
+  /**
+   * @api {post} /api/tables Save a table
+   * @apiName Save a table
+   * @apiGroup tables
+   * @apiPermission builder
+   * @apiDescription Create or update a table with this endpoint, this will function for both internal
+   * external tables.
+   *
+   * @apiParam (Body) {string} [_id] If updating an existing table then the ID of the table must be specified.
+   * @apiParam (Body) {string} [_rev] If updating an existing internal table then the revision must also be specified.
+   * @apiParam (Body) {string} type] This should either be "internal" or "external" depending on the table type -
+   * this will default to internal.
+   * @apiParam (Body) {string} [sourceId] If creating an external table then this should be set to the data source ID. If
+   * building an internal table this does not need to be set, although it will be returned as "bb_internal".
+   * @apiParam (Body) {string} name The name of the table, this will be used in the UI. To rename the table simply
+   * supply the table structure to this endpoint with the name changed.
+   * @apiParam (Body) {object} schema A key value object which has all of the columns in the table as the keys in this
+   * object. For each column a "type" and "constraints" must be specified, with some types requiring further information.
+   * More information about the schema structure can be found in the Typescript definitions.
+   * @apiParam (Body) {string} [primaryDisplay] The name of the column which should be used when displaying rows
+   * from this table as relationships.
+   * @apiParam (Body) {object[]} [indexes] Specifies the search indexes - this is deprecated behaviour with the introduction
+   * of lucene indexes. This functionality is only available for internal tables.
+   * @apiParam (Body) {object} [_rename] If a column is to be renamed then the "old" column name should be set in this
+   * structure, and the "updated", new column name should also be supplied. The schema should also be updated, this field
+   * lets the server know that a field hasn't just been deleted, that the data has moved to a new name, this will fix
+   * the rows in the table. This functionality is only available for internal tables.
+   * @apiParam (Body) {object} [dataImport] When creating an internal table it can be built from a CSV, by using the
+   * CSV validation endpoint. Send the CSV data to the validation endpoint, then put the results of that call
+   * into this property, along with the CSV and a table/rows will be built from it. This is not supported when updating
+   * or for external tables.
+   *
+   * @apiParamExample {json} Example:
+   * {
+   *   "_id": "ta_05541307fa0f4044abee071ca2a82119",
+   *   "_rev": "10-0fbe4e78f69b255d79f1017e2eeef807",
+   *   "type": "internal",
+   *   "views": {},
+   *   "name": "tableName",
+   *   "schema": {
+   *     "column": {
+   *       "type": "string",
+   *       "constraints": {
+   *         "type": "string",
+   *         "length": {
+   *           "maximum": null
+   *         },
+   *         "presence": false
+   *       },
+   *       "name": "column"
+   *     },
+   *   },
+   *   "primaryDisplay": "column",
+   *   "indexes": [],
+   *   "sourceId": "bb_internal",
+   *   "_rename": {
+   *     "old": "columnName",
+   *     "updated": "newColumnName",
+   *   },
+   *   "dataImport": {
+   *     "csvString": "column\nvalue",
+   *     "primaryDisplay": "column",
+   *     "schema": {
+   *       "column": {
+   *         "type": "string"
+   *       }
+   *     }
+   *   }
+   * }
+   *
+   * @apiSuccess {object} table The response body will contain the table structure after being cleaned up and
+   * saved to the database.
+   */
   .post(
     "/api/tables",
     // allows control over updating a table
@@ -42,22 +139,68 @@ router
     generateSaveValidator(),
     tableController.save
   )
+  /**
+   * @api {post} /api/tables/csv/validate Validate a CSV for a table
+   * @apiName Validate a CSV for a table
+   * @apiGroup tables
+   * @apiPermission builder
+   * @apiDescription When creating a new table, or importing a CSV to an existing table the CSV must be validated and
+   * converted into a Budibase schema; this endpoint does this.
+   *
+   * @apiParam (Body) {string} csvString The CSV which is to be validated as a string.
+   * @apiParam (Body) {object} [schema] When a CSV has been validated it is possible to re-validate after changing the
+   * type of a field, by default everything will be strings as there is no way to infer types. The returned schema can
+   * be updated and then returned to the endpoint to re-validate and check if the type will work for the CSV, e.g.
+   * using a number instead of strings.
+   * @apiParam (Body) {string} [tableId] If importing data to an existing table this will pull the current table and
+   * remove any fields from the CSV schema which do not exist on the table/don't match the type of the table. When
+   * importing a CSV to an existing table only fields that are present on the table can be imported.
+   *
+   * @apiSuccess {object} schema The response body will contain a "schema" object that represents the schema found for
+   * the CSV - this will be in the same format used for table schema.s
+   */
   .post(
     "/api/tables/csv/validate",
     authorized(BUILDER),
     tableController.validateCSVSchema
   )
+  /**
+   * @api {post} /api/tables/:tableId/:revId Delete a table
+   * @apiName Delete a table
+   * @apiGroup tables
+   * @apiPermission builder
+   * @apiDescription This endpoint will delete a table and all of its associated data, for this reason it is
+   * quite dangerous - it will work for internal and external tables.
+   *
+   * @apiParam {string} tableId The ID of the table which is to be deleted.
+   * @apiParam {string} [revId] If deleting an internal table then the revision must also be supplied (_rev), for
+   * external tables this can simply be set to anything, e.g. "external".
+   *
+   * @apiSuccess {string} message A message stating that the table was deleted successfully.
+   */
   .delete(
     "/api/tables/:tableId/:revId",
     paramResource("tableId"),
     authorized(BUILDER),
     tableController.destroy
   )
-  // this is currently builder only, but in the future
-  // it could be carried out by an end user in app,
-  // however some thought will need to be had about
-  // implications for automations (triggers)
-  // new trigger type, bulk rows created
+  /**
+   * @api {post} /api/tables/:tableId/:revId Import CSV to existing table
+   * @apiName Import CSV to existing table
+   * @apiGroup tables
+   * @apiPermission builder
+   * @apiDescription This endpoint will import data to existing tables, internal or external. It is used in combination
+   * with the CSV validation endpoint. Take the output of the CSV validation endpoint and pass it to this endpoint to
+   * import the data; please note this will only import fields that already exist on the table/match the type.
+   *
+   * @apiParam {string} tableId The ID of the table which the data should be imported to.
+   *
+   * @apiParam (Body) {object} dataImport This is the same as the structure used when creating an internal table with
+   * a CSV, it will have the "schema" returned from the CSV validation endpoint and the "csvString" which is to be
+   * turned into rows.
+   *
+   * @apiSuccess {string} message A message stating that the data was imported successfully.
+   */
   .post(
     "/api/tables/:tableId/import",
     paramResource("tableId"),

package/src/definitions/datasource.ts

@@ -54,6 +54,17 @@ export enum IncludeRelationships {
   EXCLUDE = 0,
 }
 
+export enum FilterTypes {
+  STRING = "string",
+  FUZZY = "fuzzy",
+  RANGE = "range",
+  EQUAL = "equal",
+  NOT_EQUAL = "notEqual",
+  EMPTY = "empty",
+  NOT_EMPTY = "notEmpty",
+  ONE_OF = "oneOf",
+}
+
 export interface QueryDefinition {
   type: QueryTypes
   displayName?: string

package/src/integrations/base/sql.ts

@@ -93,7 +93,7 @@ class InternalBuilder {
     if (filters.oneOf) {
       iterate(filters.oneOf, (key, array) => {
         const fnc = allOr ? "orWhereIn" : "whereIn"
-        query = query[fnc](key, array)
+        query = query[fnc](key, Array.isArray(array) ? array : [array])
       })
     }
     if (filters.string) {
@@ -435,8 +435,6 @@ class SqlQueryBuilder extends SqlTableQueryBuilder {
         id = results?.[0].id
       } else if (sqlClient === SqlClients.MY_SQL) {
         id = results?.insertId
-      } else if (sqlClient === SqlClients.ORACLE) {
-        id = response.outBinds[0][0]
       }
       row = processFn(
         await this.getReturningRow(queryFn, this.checkLookupKeys(id, json))

package/src/integrations/oracle.ts

@@ -348,27 +348,7 @@ module OracleModule {
       this.schemaErrors = final.errors
     }
 
-    /**
-     * Knex default returning behaviour does not work with oracle
-     * Manually add the behaviour for the return column
-     */
-    private addReturning(
-      query: SqlQuery,
-      bindings: BindParameters,
-      returnColumn: string
-    ) {
-      if (bindings instanceof Array) {
-        bindings.push({ dir: oracledb.BIND_OUT })
-        query.sql =
-          query.sql + ` returning \"${returnColumn}\" into :${bindings.length}`
-      }
-    }
-
-    private async internalQuery<T>(
-      query: SqlQuery,
-      returnColum?: string,
-      operation?: string
-    ): Promise<Result<T>> {
+    private async internalQuery<T>(query: SqlQuery): Promise<Result<T>> {
       let connection
       try {
         connection = await this.getConnection()
@@ -376,13 +356,6 @@ module OracleModule {
         const options: ExecuteOptions = { autoCommit: true }
         const bindings: BindParameters = query.bindings || []
 
-        if (
-          returnColum &&
-          (operation === Operation.CREATE || operation === Operation.UPDATE)
-        ) {
-          this.addReturning(query, bindings, returnColum)
-        }
-
         const result: Result<T> = await connection.execute<T>(
           query.sql,
           bindings,
@@ -441,13 +414,46 @@ module OracleModule {
     }
 
     async query(json: QueryJson) {
-      const primaryKeys = json.meta!.table!.primary
-      const primaryKey = primaryKeys ? primaryKeys[0] : undefined
-      const queryFn = (query: any, operation: string) =>
-        this.internalQuery(query, primaryKey, operation)
-      const processFn = (response: any) => (response.rows ? response.rows : [])
-      const output = await this.queryWithReturning(json, queryFn, processFn)
-      return output
+      const operation = this._operation(json)
+      const input = this._query(json, { disableReturning: true })
+      if (Array.isArray(input)) {
+        const responses = []
+        for (let query of input) {
+          responses.push(await this.internalQuery(query))
+        }
+        return responses
+      } else {
+        // read the row to be deleted up front for the return
+        let deletedRows
+        if (operation === Operation.DELETE) {
+          const queryFn = (query: any) => this.internalQuery(query)
+          deletedRows = await this.getReturningRow(queryFn, json)
+        }
+
+        // run the query
+        const response = await this.internalQuery(input)
+
+        // get the results or return the created / updated / deleted row
+        if (deletedRows?.rows?.length) {
+          return deletedRows.rows
+        } else if (response.rows?.length) {
+          return response.rows
+        } else {
+          // get the last row that was updated
+          if (
+            response.lastRowid &&
+            json.endpoint?.entityId &&
+            operation !== Operation.DELETE
+          ) {
+            const lastRow = await this.internalQuery({
+              sql: `SELECT * FROM \"${json.endpoint.entityId}\" WHERE ROWID = '${response.lastRowid}'`,
+            })
+            return lastRow.rows
+          } else {
+            return [{ [ operation.toLowerCase() ]: true }]
+          }
+        }
+      }
     }
   }