> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update entity records by filter
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Applies the same change to up to 500 records in one of the app's entities that match a filter, and returns how many changed.
Send `query`, a filter written the same way as the `q` parameter of [List entity records](/api-reference/list-entity-records), and `data`, the change written as MongoDB update operators on the entity's field names. For example, `{"query": {"status": "draft"}, "data": {"$set": {"status": "sent"}}}` marks every draft as sent. A field can appear in only one operator per call, and the operators you can use are:
- `$set`, `$unset`, and `$rename`
- `$inc`, `$mul`, `$min`, and `$max`
- `$currentDate`
- `$addToSet`, `$push`, and `$pull`
The values aren't checked against the entity's schema, so a field the schema doesn't declare, or a value of another type, is stored as sent.
Row-level security applies. The filter only reaches records the entity's `rls` update rule lets you change, and the rest are left alone rather than failing the call. If a field-level rule refuses the change on any matching record, the call is rejected and no records change.
When more than 500 records match, 500 of them change and `has_more` is `true`. Call again to change the rest, with a filter that no longer matches the records you've already changed, as the draft filter in the example does. A filter that still matches them changes the same records again.
Repeating `$set`, `$unset`, `$rename`, `$min`, `$max`, `$addToSet`, or `$pull` leaves the records as the first call did, so it's safe to retry. Repeating `$inc`, `$mul`, `$push`, or `$currentDate` applies the change a second time.
Unlike [Update entity record](/api-reference/update-entity-record), this doesn't trigger the app's webhooks, automations, or workflows.
This endpoint accepts a personal API key belonging to a user with access to the app. A read-only key is refused, and workspace API keys are not accepted.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json patch /api/apps/{app_id}/entities/{entity_name}/update-many
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/entities/{entity_name}/update-many:
patch:
summary: Update entity records by filter
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Applies the same change to up to 500 records in one of the app's
entities that match a filter, and returns how many changed.
Send `query`, a filter written the same way as the `q` parameter of
[List entity records](/api-reference/list-entity-records), and `data`,
the change written as MongoDB update operators on the entity's field
names. For example, `{"query": {"status": "draft"}, "data": {"$set":
{"status": "sent"}}}` marks every draft as sent. A field can appear in
only one operator per call, and the operators you can use are:
- `$set`, `$unset`, and `$rename`
- `$inc`, `$mul`, `$min`, and `$max`
- `$currentDate`
- `$addToSet`, `$push`, and `$pull`
The values aren't checked against the entity's schema, so a field the
schema doesn't declare, or a value of another type, is stored as sent.
Row-level security applies. The filter only reaches records the entity's
`rls` update rule lets you change, and the rest are left alone rather
than failing the call. If a field-level rule refuses the change on any
matching record, the call is rejected and no records change.
When more than 500 records match, 500 of them change and `has_more` is
`true`. Call again to change the rest, with a filter that no longer
matches the records you've already changed, as the draft filter in the
example does. A filter that still matches them changes the same records
again.
Repeating `$set`, `$unset`, `$rename`, `$min`, `$max`, `$addToSet`, or
`$pull` leaves the records as the first call did, so it's safe to retry.
Repeating `$inc`, `$mul`, `$push`, or `$currentDate` applies the change
a second time.
Unlike [Update entity record](/api-reference/update-entity-record), this
doesn't trigger the app's webhooks, automations, or workflows.
This endpoint accepts a personal API key belonging to a user with
access to the app. A read-only key is refused, and workspace API keys
are not accepted.
operationId: >-
update_many_entities_api_apps__app_id__entities__entity_name__update_many_patch
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app that owns the entity.
title: App Id
description: ID of the app that owns the entity.
example: 6820f3a4e7b91d003c45a1f2
- name: entity_name
in: path
required: true
schema:
type: string
description: >-
Name of the entity, exactly as [List entity
schemas](/api-reference/list-entity-schemas) reports it. Don't
pass `User` here. It doesn't fail, but it reads and writes a
separate, disconnected set of records stored under that name, not
the app's real user accounts, which are managed through their own
endpoints.
title: Entity Name
description: >-
Name of the entity, exactly as [List entity
schemas](/api-reference/list-entity-schemas) reports it. Don't pass
`User` here. It doesn't fail, but it reads and writes a separate,
disconnected set of records stored under that name, not the app's
real user accounts, which are managed through their own endpoints.
example: Invoice
requestBody:
required: true
content:
application/json:
schema:
type: object
title: UpdateEntityRecordsByFilter
required:
- query
- data
properties:
query:
type: object
additionalProperties: true
description: >-
Filter selecting the records to change, in the same form as
`q`. Send `{}` to match every record.
example:
status: draft
data:
type: object
additionalProperties: true
description: >-
The change, as one or more update operators, each mapping
field names to values.
example:
$set:
status: sent
example:
query:
status: draft
data:
$set:
status: sent
responses:
'200':
description: How many records changed.
content:
application/json:
schema:
type: object
additionalProperties: true
title: UpdateEntityRecordsByFilterResponse
description: How many records a filtered update changed.
properties:
success:
type: boolean
title: Success
description: >-
Always `true`. An update that doesn't happen returns an
error instead.
example: true
updated:
description: >-
Number of matching records the call changed. A record that
already held the new values still counts, because its
`updated_date` changes, and `0` means no record matched.
example: 42
title: Updated
type: integer
has_more:
description: >-
Whether more than 500 records matched, so only 500 of them
were changed and more may be left.
example: false
title: Has More
type: boolean
required:
- success
- updated
- has_more
'400':
description: >-
`data` is empty, uses an operator that isn't supported, isn't an
object for each operator, or names a field in more than one
operator. Also returned when `query` isn't a filter Base44 can run,
for example one with an `id` that isn't a record ID, when an
operator doesn't fit the type a field holds, or, on some apps, when
a value is over 20,000 characters.
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have access to this app, the entity's `rls` update rule or
a field-level rule refuses the change on a matching record, or your
API key is read-only.
'404':
description: App not found, or the app has no entity with this name.
'405':
description: The entity is `User`, whose records can't be updated in bulk.
'422':
description: >-
The body is missing `query` or `data`, or one of them isn't a JSON
object.
'429':
description: >-
Rate limit exceeded. The base limit is 25 requests per minute, and
this endpoint shares it with [Update entity
records](/api-reference/update-entity-records). See [Rate
limits](/developers/references/apps-api/get-started/rate-limits) for
the multiplier your plan gets.
components:
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````