Manage documents

This page describes how to manage your datastore information after you have imported documents into Discovery for Media. You can read, write, and delete documents in your datastore.

To keep your datastore up to date as document information changes, import your datastore the same way as the very first time. For help with importing your datastore, see Importing datastore information.

Upload a document

Create a single document item by using the Documents.create REST method.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data '{
        "schemaId": "default_schema",
        "jsonData": "{\"title\":\"Test document title\",\"categories\":[\"sports > clip\",\"sports > highlight\"],\"uri\":\"http://www.example.com\",\"media_type\":\"sports-game\",\"duration\":\"100s\",\"availability_start_time\":\"2022-08-26T23:00:17Z\"}"
    }' \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents?documentId=DOCUMENT_ID"

If the request is successful, the document object is returned, such as in the following example.

{
  "name": "projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID",
  "id": "DOCUMENT_ID",
   "schemaId": "default_schema",
   "jsonData": "{\"title\":\"Test document title\",\"categories\":[\"sports > clip\",\"sports > highlight\"],\"uri\":\"http://www.example.com\",\"media_type\":\"sports-game\",\"duration\":\"100s\",\"availability_start_time\":\"2022-08-26T23:00:17Z\"}"
}

Update document information

As your product catalog changes, you can refresh your catalog by uploading changes in documents. You can upload only documents that have been added or changed; you do not need to reload your entire catalog.

Update product information by using the [documents.patch][documents-patch] method.

The following example updates the title for a specific product with a full document replacement that includes the information you want to update, such as the title value.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
        "schemaId": "default_schema",
        "jsonData": "{\"title\":\"New document title\",\"categories\":[\"sports > clip\",\"sports > highlight\"],\"uri\":\"http://www.example.com\",\"media_type\":\"sports-game\",\"duration\":\"100s\",\"availability_start_time\":\"2022-08-26T23:00:17Z\"}"
    }" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID"

If the request is successful, the document object is returned, such as in the following example.

{
  "name": "projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID",
  "id": "DOCUMENT_ID",
  "schemaId": "default_schema",
  "jsonData": "{\"title\":\"New document title\",\"categories\":[\"sports > clip\",\"sports > highlight\"],\"uri\":\"http://www.example.com\",\"media_type\":\"sports-game\",\"duration\":\"100s\",\"availability_start_time\":\"2022-08-26T23:00:17Z\"}"
}

Delete document information

Although Discovery for Media provides a way to delete documents from your datastore, keep in mind that if you record a user event that relates to a document item that has been deleted, Discovery for Media cannot process the user event properly and it might be deleted.

Delete a document by using the delete method, replacing DOCUMENT_ID with the ID of the document you want to delete.

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID"

Retrieve a document item

You retrieve a document by making a GET request to the documents endpoint, replacing DOCUMENT_ID with the ID of the document you want to retrieve:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID"

You should see output similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/global/dataStores/default_data_store/branches/0/documents/DOCUMENT_ID",
  "id": "DOCUMENT_ID",
  "schemaId": "default_schema",
  "jsonData": "{\"title\":\"New document title\",\"categories\":[\"sports > clip\",\"sports > highlight\"],\"uri\":\"http://www.example.com\",\"media_type\":\"sports-game\",\"duration\":\"100s\",\"availability_start_time\":\"2022-08-26T23:00:17Z\"}"
}

View aggregated information about your datastore

You can view aggregated information about your datastore and preview uploaded documents in the in the Documents tab on the Discovery Engine Data page.

Change document types

We do not recommend changing document types.

Discovery for Media determines the document level by checking the document's parent_document_id. If its parent_document_id field is unused, empty, or matches the document's id value, Discovery for Media considers the document as a parent type. If the parent_document_id value exists and does nto match the id value, Discovery for Media considers the document as a child type.

If a document's type changes or its parent_document_id was specified incorrectly, you must delete the document and create it with the updated parent_document_id.