items

Creates, updates, deletes, gets or lists an items resource.

Overview

Name	items
Type	Resource
Id	cloudflare.aisearch.items

Fields

The following fields are returned by SELECT queries:

get

Returns a AI Search Item detail.

Name	Datatype	Description
id	string
source_id	string	Identifies which data source this item belongs to. "builtin" for uploaded files, "{type}:{source}" for external sources, null for legacy items.
checksum	string
chunks_count	integer
created_at	string (date-time)
error	string
file_size	number
key	string
last_seen_at	string (date-time)
namespace	string
next_action	string	(INDEX, DELETE, )
status	string	(queued, running, completed, error, skipped, outdated)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	id, item_id, account_id, name		Retrieves a specific indexed item from an AI Search instance.
upload	insert	id, account_id, name, file		Uploads a file to a managed AI Search instance via multipart/form-data (max 4MB).
sync	update	id, item_id, account_id, name, next_action		Syncs an item to an AI Search instance index.
create_or_update	replace	id, account_id, name, key, next_action		Creates or updates an indexed item in an AI Search instance.
delete	delete	id, item_id, account_id, name		Deletes a file from a managed AI Search instance and triggers a reindex.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
id	string	Resource ID.
item_id	string
name	string	Resource name.

SELECT examples

get

Retrieves a specific indexed item from an AI Search instance.

SELECT
id,
source_id,
checksum,
chunks_count,
created_at,
error,
file_size,
key,
last_seen_at,
namespace,
next_action,
status
FROM cloudflare.aisearch.items
WHERE id = '{{ id }}' -- required
AND item_id = '{{ item_id }}' -- required
AND account_id = '{{ account_id }}' -- required
AND name = '{{ name }}' -- required
;

INSERT examples

upload

Uploads a file to a managed AI Search instance via multipart/form-data (max 4MB).

INSERT INTO cloudflare.aisearch.items (
file,
metadata,
wait_for_completion,
id,
account_id,
name
)
SELECT 
'{{ file }}' /* required */,
'{{ metadata }}',
{{ wait_for_completion }},
'{{ id }}',
'{{ account_id }}',
'{{ name }}'
RETURNING
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: items
props:
  - name: id
    value: "{{ id }}"
    description: Required parameter for the items resource.
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the items resource.
  - name: name
    value: "{{ name }}"
    description: Required parameter for the items resource.
  - name: file
    value: "{{ file }}"
    description: |
      The file to upload (max 4MB). Filename must not exceed 128 characters.
  - name: metadata
    value: "{{ metadata }}"
    description: |
      JSON string of custom metadata key-value pairs.
  - name: wait_for_completion
    value: {{ wait_for_completion }}
    description: |
      Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false.
    default: false

UPDATE examples

sync

Syncs an item to an AI Search instance index.

UPDATE cloudflare.aisearch.items
SET 
next_action = '{{ next_action }}',
wait_for_completion = {{ wait_for_completion }}
WHERE 
id = '{{ id }}' --required
AND item_id = '{{ item_id }}' --required
AND account_id = '{{ account_id }}' --required
AND name = '{{ name }}' --required
AND next_action = '{{ next_action }}' --required
RETURNING
result,
success;

REPLACE examples

create_or_update

Creates or updates an indexed item in an AI Search instance.

REPLACE cloudflare.aisearch.items
SET 
key = '{{ key }}',
next_action = '{{ next_action }}',
wait_for_completion = {{ wait_for_completion }}
WHERE 
id = '{{ id }}' --required
AND account_id = '{{ account_id }}' --required
AND name = '{{ name }}' --required
AND key = '{{ key }}' --required
AND next_action = '{{ next_action }}' --required
RETURNING
result,
success;

DELETE examples

delete

Deletes a file from a managed AI Search instance and triggers a reindex.

DELETE FROM cloudflare.aisearch.items
WHERE id = '{{ id }}' --required
AND item_id = '{{ item_id }}' --required
AND account_id = '{{ account_id }}' --required
AND name = '{{ name }}' --required
;