Document Creating a Datastore Index in a Non-Default Database with the Admin Client

[pentium10]

The current documentation for the Datastore Admin Client lacks examples of how to create an index in a specific, non-default database. The existing methods and examples only appear to work for the (default) database. This is a significant gap for users who leverage multiple databases within a single project and need to manage indexes programmatically.

For instance, when developing an application that uses a dedicated Datastore database for session storage, such as an Agent Development Kit, the setup process should be automated. While other backends like SQLite or Postgres allow for automatic setup, doing so with a non-default Datastore database is not straightforward due to the lack of documentation for index creation in this context.

When attempting to create an index, the operation succeeds only when targeting the (default) database. There is no clear, documented way to specify a different database when using the Datastore Admin Client. While the gcloud command-line tool provides a --database flag for this purpose, a corresponding, documented parameter or method for the admin client library is not available.

Describe the solution you'd like

The official documentation for the Google Cloud Datastore Admin Client should be updated to include a clear example of how to create an index under a specified, non-default database. This would likely involve showcasing an additional parameter in the relevant index creation methods to specify the database ID.

Describe alternatives you've considered

A possible alternative is to use the gcloud datastore indexes create command with the --database flag as a workaround. However, this is not ideal when the application infrastructure is managed programmatically through the Python client libraries. It introduces a dependency on the gcloud CLI and requires shelling out from the application, which is less clean and portable.

Additional context

Here is a snippet of the code that is being used, which only works for the (default) database. The goal is to be able to specify a different database for the index creation.

from google.cloud.datastore_admin_v1.services import datastore_admin
from google.cloud.datastore_admin_v1.types import Index
from google.cloud.datastore_admin_v1.types import datastore_admin as datastore_admin_types

def create_datastore_index(project_id: str, database_id: str, kind: str, property_name: str):
    """
    Creates a Datastore index for a specific kind and property.

    Args:
        project_id: The ID of the Google Cloud project.
        database_id: The ID of the Datastore database.
        kind: The kind for which the index is to be created.
        property_name: The property for which the index is to be created.
    """
    try:
        admin_client = datastore_admin.DatastoreAdminClient()

        # How to specify the database_id here is the core issue.
        # The following request does not have a parameter for the database.
        request = datastore_admin_types.CreateIndexRequest(
            project_id=project_id,
            index=Index(
                kind=kind,
                ancestor=Index.AncestorMode.NONE,
                properties=[
                    Index.IndexedProperty(
                        name=property_name,
                        direction=Index.Direction.ASCENDING,
                    ),
                ],
            ),
        )

        # This operation only works on the '(default)' database.
        operation = admin_client.create_index(request=request)
        print(f"Waiting for index creation operation to complete for database '{database_id}'...")
        operation.result()
        print("Index created successfully.")

    except Exception as e:
        print(f"An error occurred during index creation: {e}")

# Example usage:
# create_datastore_index("my-gcp-project", "my-non-default-database", "MyEntityKind", "my_property")

This feature request addresses the need for clear documentation to enable developers to fully utilize the Datastore Admin Client's capabilities in a multi-database environment.