googleapis / googleapis/google-cloud-java

[java-firestore] Improve the documentation about how to use OperationsClient after FirestoreAdminClient.exportDocuments()

Open
#13,130 0 comments 0 reactions 0 assignees View on GitHub
api: firestore
Dominant language
Java
Stars
2.1k
Forks
1.2k
Avg merge
1d 23h
Merged PRs (30d)
154

Description

Apologies if I misread the documentation, but I think I found several gaps in the documentation trying to query operations after launching `FirestoreAdminClient.exportDocuments`. Most of the issues are caused because the way to use `OperationsClient` specifically to track Firestore Operations is not really documented (or I couldn't find it).

* The [javadoc for OperationsClient](https://github.com/googleapis/gax-java/blob/878bcf2da215e14d9e3bcb4717b85d867f149cee/gax-grpc/src/main/java/com/google/longrunning/OperationsClient.java#L243) generically documents `name` as "The name of the operation collection". The documentation [in the proto file](https://github.com/googleapis/java-firestore/blob/aabd4ac4e43e1c58ec25e51117980f4396a3e8d9/proto-google-cloud-firestore-admin-v1/src/main/proto/google/firestore/admin/v1/firestore_admin.proto#L417) documents the expected format, but does not link to the format to be used when invoking `OperationClient.listOperations`.
* The [javadoc for FirestoreAdminClient](https://github.com/googleapis/java-firestore/blob/3aea7bcfaebb493c1397a6856be92783700dbca4/google-cloud-firestore-admin/src/main/java/com/google/cloud/firestore/v1/FirestoreAdminClient.java#L94) says that "by default, ListOperations will only return in progress and failed operations" but it does not describe what a running / successful / failed operation looks like, and particularly how to identify a failed operation.
* The way to unpack `ExportDocumentsMetadata` from an `Operation` is not documented. I'm using `op.getMetadata().unpack(ExportDocumentsMetadata.class)`.
* I could not find any documentation about supported filters when invoking `OperationsClient.listOperations`. It's only documented that one can use `done:true`. For example, all variants that I could try of searching for `metadata.@type:type.googleapis.com/google.firestore.admin.v1.ExportDocumentsMetadata` did not work, so I suppose that's not supported. It would be good to know what is supported.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.