{"record":{"id":"032471e21ac68c3b","repo":"apache/beam","slug":"unable-to-parallelize-the-given-query","errorCode":null,"errorMessage":"Unable to parallelize the given query: {}","messagePattern":"Unable to parallelize the given query: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/datastore/DatastoreV1.java","lineNumber":1064,"sourceCode":"        } else {\n          estimatedNumSplits = numSplits;\n        }\n\n        LOG.info(\"Splitting the query into {} splits\", estimatedNumSplits);\n        List<Query> querySplits;\n        try {\n          querySplits =\n              splitQuery(\n                  options.getProjectId(),\n                  options.getDatabaseId(),\n                  query,\n                  options.getNamespace(),\n                  datastore,\n                  querySplitter,\n                  estimatedNumSplits,\n                  readTime);\n        } catch (Exception e) {\n          LOG.warn(\"Unable to parallelize the given query: {}\", query, e);\n          querySplits = ImmutableList.of(query);\n        }\n\n        // assign unique keys to query splits.\n        for (Query subquery : querySplits) {\n          c.output(subquery);\n        }\n      }\n\n      @Override\n      public void populateDisplayData(DisplayData.Builder builder) {\n        super.populateDisplayData(builder);\n        builder.include(\"options\", options);\n        if (numSplits > 0) {\n          builder.add(\n              DisplayData.item(\"numQuerySplits\", numSplits)\n                  .withLabel(\"Requested number of Query splits\"));\n        }","sourceCodeStart":1046,"sourceCodeEnd":1082,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/datastore/DatastoreV1.java#L1046-L1082","documentation":"During Read expansion, Beam tries to use the Datastore query splitter to divide the query into multiple sub-queries for parallel execution. If splitting fails for any reason (query not splittable, splitter unavailable, split limit too low, or any exception), the connector logs this warning and falls back to a single unsplit query, meaning the read will run with reduced (single-reader) parallelism.","triggerScenarios":"DatastoreIO.read() on a query the QuerySplitter cannot split (e.g. query without an ancestor or with an inequality filter on a non-id field, or GQL-translated queries), estimatedNumSplits below minimum supported, or split requests throwing exceptions (quota/API errors).","commonSituations":"Users reading a single Kind with filters that prevent splitting; running with numQuerySplits set higher than the API allows; reads from namespaces or with readTime where splitter support is limited.","solutions":["Restructure the query so it is splittable: query a top-level Kind without restrictive inequality filters, or add an ancestor if appropriate.","Lower withNumQuerySplits() to a value the Cloud Datastore splitter supports (splitting may fail if requested splits are too granular for the data size).","Accept the warning if data volume is small; the read still completes with one reader.","Check the attached exception to see if the underlying split request failed due to permissions/quota and fix that instead."],"exampleFix":"// before\ndatastoreIO.read().withQuery(query).withNumQuerySplits(10000)\n// after\ndatastoreIO.read().withQuery(query).withNumQuerySplits(20)","handlingStrategy":"fallback","validationCode":"// Java: prefer queries the splitter supports\nif (query.hasFilter() && !isEqualityOnlyFilter(query.getFilter())) {\n  LOG.info(\"Query may not be splittable; expect single-reader fallback\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep numQuerySplits modest (tens, not thousands).","Design queries on top-level Kinds with equality filters or no filters for best splitting.","Treat the warning as a parallelism signal, not an error."],"tags":["gcp-datastore","query-splitting","parallelism","beam-io"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}