Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

microappdata

description

Returns rows from a Datatable (historically called a Microapp). Use this endpoint when you need to read a collection of rows, optionally with filters, sorting, pagination, or parent-child filtering through embeddingRowID.

For the canonical explanation of row metadata, linked-table structures, and embeddingRowID, see Row Metadata and Relationships.

For a compact list of parameters and caveats across all REST endpoints, see Endpoint Parameter Guide.

parameters

The X-Auth-Token and X-User-Id are derived from the values authToken and userId returned from the login endpoint and are used in the HTTP header.

Typical authenticated request headers:

X-Auth-Token: <authToken from /api/login>
X-User-Id: <userId from /api/login>
Content-Type: application/json

Resource

{
  "microAppID": "<insert microapp id here>",
  "searchFilter": [],
  "optSearchFilters": [],
  "optViewFilters": [],
  "optViewSort": [],
  "optLimit": 100,
  "optIsVectorSearch": false,
  "optVectorSearchString": "<optional semantic search string>",
  "optVectorSearchNumCandidates": 10,
  "buzzyFormat": false
}

The endpoint also accepts resultContentType, optIsStatic, and optExcludeMicroApps for advanced use cases.

response

A JSON document containing matching rows. Each row contains:

  • user-defined row data

  • system metadata such as _id, userID, submitted, and sometimes embeddingRowID

The success payload is returned as body.microAppRows.

See Row Metadata and Relationships.

Private Data behavior

The microappdata endpoint follows the same server-side row, field, and Private Data rules as the Buzzy app runtime.

  • If the authenticated caller can view a Private Data field, the response can include the accessible value.

  • If the caller cannot view the field, Basic Private Data is masked or redacted and Sensitive Private Data is hidden.

  • Field view and Field edit are evaluated after row access. A caller must be allowed to see the row and the field before the raw value is returned.

  • Viewer and Team Viewer policies apply to API callers the same way they apply in the runtime app.

  • Encrypted Private Data fields should not be used for normal search, sort, or vector search.

  • Use non-private metadata fields for filters, reports, and ordering.

This means REST integrations should authenticate as the user or narrowly scoped integration account whose access matches the use case.

Private Data reveal audit entries are intended for user-initiated reveal events. Normal list/query API calls still use server-side output shaping and should be tested with allowed and denied users.

example

Only the microAppID needs to be specified in the simplest case. Its value can be found on the properties page of the Datatable in the editor.

Example of fetching all data from a Microapp:

filter example

A filter can be applied to narrow the results of the fetch using the optSearchFilters array. In the optSearchFilters the resourceID is the same as the microappid. The fieldID is an identifier that corresponds to the Field Name. It can be found in the field properties in the editor.

Example of fetching data from a microapp with a filter:

sort example

The data fetched from the Microapp can be sorted. The order and field parameters are used in the searchFilter to specify which Microapp sort field and if it is ascending or descending. The sort fields are configured in the Microapp Results Tab. Sort field 1 corresponds to the field value 1 and so on. Where order is either 1 = ascending or -1 = descending.

Example fetching microapp rows using Sort Field 1.

paging example

Pagination is achieved using the skip and limit parameters. The skip parameter specifies the number of results to skip at the beginning. The limit parameter specifies the maximum number of results to return.

Always pass both limit and skip for paged reads, and use a stable sort when paging through data that may be updated while you read it. Prefer numeric values for limit and skip.

Example fetching microapp rows using pagination.

The buzzyFormat parameter is used to output raw data instead of JSON. This is used only in exceptional situations and please contact your buzzy representative for more information.

finding embedded row data example

When you have Sub-Tables (1:M) you have a parent -> child relationship. Each child row stores the parent row ID in embeddingRowID. This is the canonical field for sub-table relationships in Buzzy.

For example, you might have a row for each invoice and then query the Invoice Lines child table for only the rows belonging to one invoice.

Example fetching rows using embeddingRowID. In this example, sortVal2 represents an approved flag, so the query returns only approved invoice lines for one parent invoice:

See Row Metadata and Relationships for the canonical explanation.

using mongoDB query syntax example

Buzzy is based on Mongo DB and allows you to use MongDB's query syntax, allow for more complex queries. Each object in the optViewFilters array is AND'd. Note for OR you can include that in each object.

Example fetching microapp rows using a MongoDB like query where sortVal5 is between lowVal and highVal

geo/spatial query examples

Buzzy supports MongoDB's geospatial queries through the sortValGeometry field. This allows you to search for data based on geographic locations and boundaries.

Example 1: Searching within a radius

This example searches for data within a circular area around a specific point (Manly, NSW in this case):

Example 2: Searching within a polygon

This example searches for data within a polygon boundary (roughly the outline of Australia):

Example 3: Finding data within a map's bounding box

A common use case is to find data that matches the current bounding box of a map as a user pans around. This example shows how to query for data within the current map viewport:

For a complete implementation example of a map with location data, see the Event Locations Map example.

For more info on MongoDB queries see here and for some additional Buzzy examples with custom code widgets, including geospatial queries, see here

You can also use these geo/spatial query parameters with the Node.js API Client and the Async API in Code Widgets.

See Also

PreviousRow Metadata and RelationshipsNextmicroappdata/row

Last updated