feat(bigquery): add internal listProjects API to core client (#13429)

b/521443900

This PR introduces support for fetching a list of GCP projects via the
BigQuery API. This functionality is being exposed primarily to support
cross-project dataset resolution in the native BigQuery JDBC driver.

**Changes included:**
* **Domain Model:** Added `Project` domain model representing a BigQuery
project (`@BetaApi`).
* **Client Interface:** Added `listProjects(ProjectListOption...
options)` to the `BigQuery` client interface, marked as `@InternalApi`
to preserve the public GA surface.
* **SPI Layer:** Added `listProjects` mapping to `BigQueryRpc` and
implemented the underlying HTTP execution in `HttpBigQueryRpc`,
including pagination and OpenTelemetry tracing support.
* **Implementation:** Implemented `ProjectPageFetcher` inside
`BigQueryImpl` to seamlessly handle paginated project results.
* **Testing:** Added unit test coverage in `BigQueryImplTest` and
`HttpBigQueryRpcTest`.

Author: keshavdandeva

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java

@@ -306,6 +306,24 @@ public static DatasetListOption all() {
     }
   }
 
+  /** Class for specifying project list options. */
+  @BetaApi
+  class ProjectListOption extends Option {
+    private static final long serialVersionUID = -7256063598324265038L;
+
+    private ProjectListOption(BigQueryRpc.Option option, Object value) {
+      super(option, value);
+    }
+
+    public static ProjectListOption pageSize(long pageSize) {
+      return new ProjectListOption(BigQueryRpc.Option.MAX_RESULTS, pageSize);
+    }
+
+    public static ProjectListOption pageToken(String pageToken) {
+      return new ProjectListOption(BigQueryRpc.Option.PAGE_TOKEN, pageToken);
+    }
+  }
+
   /** Class for specifying dataset get, create and update options. */
   class DatasetOption extends Option {
 
@@ -951,6 +969,15 @@ public int hashCode() {
    */
   Page<Dataset> listDatasets(DatasetListOption... options);
 
+  /**
+   * Lists the projects accessible to the caller.
+   *
+   * @param options options for listing projects
+   * @return a page of projects
+   */
+  @BetaApi
+  Page<Project> listProjects(ProjectListOption... options);
+
   /**
    * Lists the datasets in the provided project. This method returns partial information on each
    * dataset: ({@link Dataset#getDatasetId()}, {@link Dataset#getFriendlyName()} and {@link

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQueryImpl.java

@@ -25,6 +25,7 @@
 import com.google.api.gax.paging.Page;
 import com.google.api.services.bigquery.model.ErrorProto;
 import com.google.api.services.bigquery.model.GetQueryResultsResponse;
+import com.google.api.services.bigquery.model.ProjectList;
 import com.google.api.services.bigquery.model.QueryRequest;
 import com.google.api.services.bigquery.model.TableDataInsertAllRequest;
 import com.google.api.services.bigquery.model.TableDataInsertAllRequest.Rows;
@@ -65,6 +66,25 @@
 
 final class BigQueryImpl extends BaseService<BigQueryOptions> implements BigQuery {
 
+  private static class ProjectPageFetcher implements NextPageFetcher<Project> {
+
+    private static final long serialVersionUID = 1L;
+    private final Map<BigQueryRpc.Option, ?> requestOptions;
+    private final BigQueryOptions serviceOptions;
+
+    ProjectPageFetcher(
+        BigQueryOptions serviceOptions, String cursor, Map<BigQueryRpc.Option, ?> optionMap) {
+      this.requestOptions =
+          PageImpl.nextRequestOptions(BigQueryRpc.Option.PAGE_TOKEN, cursor, optionMap);
+      this.serviceOptions = serviceOptions;
+    }
+
+    @Override
+    public Page<Project> getNextPage() {
+      return listProjects(serviceOptions, requestOptions);
+    }
+  }
+
   private static class DatasetPageFetcher implements NextPageFetcher<Dataset> {
 
     private static final long serialVersionUID = -3057564042439021278L;
@@ -307,6 +327,72 @@ public com.google.api.services.bigquery.model.Dataset call() throws IOException
     }
   }
 
+  @Override
+  @BetaApi
+  public Page<Project> listProjects(ProjectListOption... options) {
+    Span projectsList = null;
+    if (getOptions().isOpenTelemetryTracingEnabled()
+        && getOptions().getOpenTelemetryTracer() != null) {
+      projectsList =
+          getOptions()
+              .getOpenTelemetryTracer()
+              .spanBuilder("com.google.cloud.bigquery.BigQuery.listProjects")
+              .setAllAttributes(otelAttributesFromOptions(options))
+              .startSpan();
+    }
+    try (Scope projectsListScope = projectsList != null ? projectsList.makeCurrent() : null) {
+      return listProjects(getOptions(), optionMap(options));
+    } finally {
+      if (projectsList != null) {
+        projectsList.end();
+      }
+    }
+  }
+
+  private static Page<Project> listProjects(
+      final BigQueryOptions serviceOptions, final Map<BigQueryRpc.Option, ?> optionsMap) {
+    try {
+      Tuple<String, Iterable<ProjectList.Projects>> result =
+          BigQueryRetryHelper.runWithRetries(
+              new Callable<Tuple<String, Iterable<ProjectList.Projects>>>() {
+                @Override
+                public Tuple<String, Iterable<ProjectList.Projects>> call() {
+                  return serviceOptions.getBigQueryRpcV2().listProjects(optionsMap);
+                }
+              },
+              serviceOptions.getRetrySettings(),
+              serviceOptions.getResultRetryAlgorithm(),
+              serviceOptions.getClock(),
+              EMPTY_RETRY_CONFIG,
+              serviceOptions.isOpenTelemetryTracingEnabled(),
+              serviceOptions.getOpenTelemetryTracer());
+      String nextPageToken = result.x();
+      Iterable<Project> projects =
+          Iterables.transform(
+              result.y() != null ? result.y() : ImmutableList.<ProjectList.Projects>of(),
+              new Function<ProjectList.Projects, Project>() {
+                @Override
+                public Project apply(ProjectList.Projects projectPb) {
+                  return new Project(
+                      projectPb.getId(),
+                      projectPb.getNumericId() != null
+                          ? String.valueOf(projectPb.getNumericId())
+                          : null,
+                      projectPb.getProjectReference() != null
+                          ? projectPb.getProjectReference().getProjectId()
+                          : null,
+                      projectPb.getFriendlyName());
+                }
+              });
+      return new PageImpl<>(
+          new ProjectPageFetcher(serviceOptions, nextPageToken, optionsMap),
+          nextPageToken,
+          projects);
+    } catch (BigQueryRetryHelperException e) {
+      throw BigQueryException.translateAndThrow(e);
+    }
+  }
+
   @Override
   public Table create(TableInfo tableInfo, TableOption... options) {
     final com.google.api.services.bigquery.model.Table tablePb =

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Project.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.bigquery;
+
+import com.google.api.core.BetaApi;
+import java.io.Serializable;
+import java.util.Objects;
+import javax.annotation.Nullable;
+
+/**
+ * Google BigQuery Project information. A project is the top-level container for Google Cloud
+ * resources, and holds BigQuery dataset collections. This class wraps a BigQuery project resource,
+ * providing details such as the project's unique alphanumeric ID, numeric project number, and
+ * friendly display name.
+ *
+ * <p>Objects of this class can be obtained by listing projects accessible to the caller using
+ * {@link BigQuery#listProjects(BigQuery.ProjectListOption...)}.
+ *
+ * @see <a href="https://cloud.google.com/bigquery/docs/reference/rest/v2/projects/list">Projects:
+ *     list</a>
+ */
+@BetaApi
+public class Project implements Serializable {
+  private static final long serialVersionUID = -8123877292090683890L;
+
+  private final String id;
+  private final String numericId;
+  private final String projectId;
+  private final String friendlyName;
+
+  public Project(String id, String numericId, String projectId, String friendlyName) {
+    this.id = id;
+    this.numericId = numericId;
+    this.projectId = projectId;
+    this.friendlyName = friendlyName;
+  }
+
+  /** Returns the resource ID of the project. */
+  public String getId() {
+    return id;
+  }
+
+  /** Returns the unique numeric project number. */
+  @Nullable
+  public String getNumericId() {
+    return numericId;
+  }
+
+  /** Returns the unique alphanumeric project ID. */
+  @Nullable
+  public String getProjectId() {
+    return projectId;
+  }
+
+  /** Returns the user-defined display name of the project. */
+  @Nullable
+  public String getFriendlyName() {
+    return friendlyName;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (o == null || getClass() != o.getClass()) return false;
+    Project project = (Project) o;
+    return Objects.equals(id, project.id)
+        && Objects.equals(numericId, project.numericId)
+        && Objects.equals(projectId, project.projectId)
+        && Objects.equals(friendlyName, project.friendlyName);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(id, numericId, projectId, friendlyName);
+  }
+
+  @Override
+  public String toString() {
+    return "Project{"
+        + "id='"
+        + id
+        + '\''
+        + ", numericId='"
+        + numericId
+        + '\''
+        + ", projectId='"
+        + projectId
+        + '\''
+        + ", friendlyName='"
+        + friendlyName
+        + '\''
+        + '}';
+  }
+}

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/spi/v2/BigQueryRpc.java

@@ -16,6 +16,7 @@
 
 package com.google.cloud.bigquery.spi.v2;
 
+import com.google.api.core.InternalApi;
 import com.google.api.core.InternalExtensionOnly;
 import com.google.api.services.bigquery.Bigquery.Jobs.Query;
 import com.google.api.services.bigquery.model.Dataset;
@@ -108,6 +109,15 @@ Boolean getBoolean(Map<Option, ?> options) {
    */
   Tuple<String, Iterable<Dataset>> listDatasets(String projectId, Map<Option, ?> options);
 
+  /**
+   * Lists the projects accessible to the caller, keyed by page token.
+   *
+   * @throws BigQueryException upon failure
+   */
+  @InternalApi
+  Tuple<String, Iterable<com.google.api.services.bigquery.model.ProjectList.Projects>> listProjects(
+      Map<Option, ?> options);
+
   /**
    * Creates a new dataset.
    *

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/spi/v2/HttpBigQueryRpc.java

@@ -50,6 +50,7 @@
 import com.google.api.services.bigquery.model.Model;
 import com.google.api.services.bigquery.model.ModelReference;
 import com.google.api.services.bigquery.model.Policy;
+import com.google.api.services.bigquery.model.ProjectList;
 import com.google.api.services.bigquery.model.QueryRequest;
 import com.google.api.services.bigquery.model.QueryResponse;
 import com.google.api.services.bigquery.model.Routine;
@@ -261,6 +262,49 @@ public Tuple<String, Iterable<Dataset>> listDatasetsSkipExceptionTranslation(
         });
   }
 
+  @Override
+  public Tuple<String, Iterable<ProjectList.Projects>> listProjects(Map<Option, ?> options) {
+    try {
+      validateRPC();
+      Bigquery.Projects.List request = bigquery.projects().list();
+      Long maxResults = Option.MAX_RESULTS.getLong(options);
+      if (maxResults != null) {
+        request.setMaxResults(maxResults);
+      }
+      String pageToken = Option.PAGE_TOKEN.getString(options);
+      if (pageToken != null) {
+        request.setPageToken(pageToken);
+      }
+      request
+          .getRequestHeaders()
+          .set("x-goog-otel-enabled", this.options.isOpenTelemetryTracingEnabled());
+
+      String gcpResourceDestinationId = RESOURCE_PROJECT_PREFIX + this.options.getProjectId();
+
+      return executeWithSpan(
+          createRpcTracingSpan(
+              "com.google.cloud.bigquery.BigQueryRpc.listProjects",
+              "ProjectService",
+              "ListProjects",
+              gcpResourceDestinationId,
+              request.getUriTemplate(),
+              options),
+          span -> {
+            if (span != null) {
+              span.setAttribute("bq.rpc.page_token", request.getPageToken());
+            }
+            ProjectList projectList = request.execute();
+            Iterable<ProjectList.Projects> projects = projectList.getProjects();
+            if (span != null) {
+              span.setAttribute("bq.rpc.next_page_token", projectList.getNextPageToken());
+            }
+            return Tuple.of(projectList.getNextPageToken(), projects);
+          });
+    } catch (IOException e) {
+      throw translate(e);
+    }
+  }
+
   @Override
   public Dataset create(Dataset dataset, Map<Option, ?> options) {
     try {

java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/BigQueryImplTest.java

@@ -41,6 +41,8 @@
 import com.google.api.services.bigquery.model.GetQueryResultsResponse;
 import com.google.api.services.bigquery.model.JobConfigurationQuery;
 import com.google.api.services.bigquery.model.JobStatistics;
+import com.google.api.services.bigquery.model.ProjectList;
+import com.google.api.services.bigquery.model.ProjectReference;
 import com.google.api.services.bigquery.model.QueryRequest;
 import com.google.api.services.bigquery.model.TableCell;
 import com.google.api.services.bigquery.model.TableDataInsertAllRequest;
@@ -777,6 +779,50 @@ void testListDatasetsWithOptions() throws IOException {
     verify(bigqueryRpcMock).listDatasetsSkipExceptionTranslation(PROJECT, DATASET_LIST_OPTIONS);
   }
 
+  @Test
+  void testListProjects() {
+    bigquery = options.getService();
+    ProjectList.Projects p1 =
+        new ProjectList.Projects()
+            .setId("id1")
+            .setNumericId(BigInteger.valueOf(111L))
+            .setProjectReference(new ProjectReference().setProjectId("p-1"))
+            .setFriendlyName("fn1");
+    ProjectList.Projects p2 =
+        new ProjectList.Projects()
+            .setId("id2")
+            .setNumericId(BigInteger.valueOf(222L))
+            .setProjectReference(new ProjectReference().setProjectId("p-2"))
+            .setFriendlyName("fn2");
+    ImmutableList<ProjectList.Projects> projectsPb = ImmutableList.of(p1, p2);
+    Tuple<String, Iterable<ProjectList.Projects>> result = Tuple.of(CURSOR, projectsPb);
+
+    when(bigqueryRpcMock.listProjects(EMPTY_RPC_OPTIONS)).thenReturn(result);
+
+    Page<Project> page = bigquery.listProjects();
+    assertEquals(CURSOR, page.getNextPageToken());
+
+    Project expected1 = new Project("id1", "111", "p-1", "fn1");
+    Project expected2 = new Project("id2", "222", "p-2", "fn2");
+    assertArrayEquals(
+        new Project[] {expected1, expected2}, Iterables.toArray(page.getValues(), Project.class));
+    verify(bigqueryRpcMock).listProjects(EMPTY_RPC_OPTIONS);
+  }
+
+  @Test
+  void testListEmptyProjects() {
+    bigquery = options.getService();
+    ImmutableList<ProjectList.Projects> projectsPb = ImmutableList.of();
+    Tuple<String, Iterable<ProjectList.Projects>> result = Tuple.of(null, projectsPb);
+
+    when(bigqueryRpcMock.listProjects(EMPTY_RPC_OPTIONS)).thenReturn(result);
+
+    Page<Project> page = bigquery.listProjects();
+    assertNull(page.getNextPageToken());
+    assertArrayEquals(new Project[0], Iterables.toArray(page.getValues(), Project.class));
+    verify(bigqueryRpcMock).listProjects(EMPTY_RPC_OPTIONS);
+  }
+
   @Test
   void testDeleteDataset() throws IOException {
     when(bigqueryRpcMock.deleteDatasetSkipExceptionTranslation(PROJECT, DATASET, EMPTY_RPC_OPTIONS))