{"record":{"id":"af9735c41aa5cab2","repo":"apache/seatunnel","slug":"query-collection-num-error","errorCode":"QUERY_COLLECTION_NUM_ERROR","errorMessage":"QUERY_COLLECTION_NUM_ERROR.getDescription()","messagePattern":"QUERY_COLLECTION_NUM_ERROR\\.getDescription\\(\\)","errorType":"error_code","errorClass":"TypesenseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/client/TypesenseClient.java","lineNumber":284,"sourceCode":"    public boolean deleteCollectionData(String collection, String id) {\n        try {\n            tsClient.collections(collection).documents(id).delete();\n        } catch (Exception e) {\n            log.error(DELETE_COLLECTION_ERROR.getDescription());\n            throw new TypesenseConnectorException(\n                    DELETE_COLLECTION_ERROR, DELETE_COLLECTION_ERROR.getDescription());\n        }\n        return true;\n    }\n\n    public long collectionDocNum(String collection) {\n        SearchParameters q = new SearchParameters().q(\"*\");\n        try {\n            SearchResult searchResult = tsClient.collections(collection).documents().search(q);\n            return searchResult.getFound();\n        } catch (Exception e) {\n            log.error(QUERY_COLLECTION_NUM_ERROR.getDescription());\n            throw new TypesenseConnectorException(\n                    QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription());\n        }\n    }\n}\n","sourceCodeStart":266,"sourceCodeEnd":289,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/client/TypesenseClient.java#L266-L289","documentation":"collectionDocNum counts documents in a Typesense collection by issuing a wildcard search (q=*) and returning SearchResult.getFound(). If the search call throws (unreachable server, nonexistent collection, bad API key, malformed query), the client wraps it in TypesenseConnectorException with QUERY_COLLECTION_NUM_ERROR.","triggerScenarios":"typesenseClient.collectionDocNum(collection) performs tsClient.collections(collection).documents().search(q) and the server returns an error or the request fails at the network level. Typically called during sink/source initialization to size or validate the collection.","commonSituations":"Collection name typo in configuration; Typesense API key lacking search permission; Typesense node down or wrong port; version mismatch where the search endpoint path differs.","solutions":["Verify collection name and API key (key must have documents:search permission on the target collection).","Confirm Typesense reachability with a direct REST call, e.g. GET /collections/<name> (also returns num_documents without a search).","If only a count is needed, use the collection metadata endpoint instead of a wildcard search.","Capture/log the underlying exception to see the real HTTP status before retrying."],"exampleFix":"// before\n} catch (Exception e) {\n    log.error(QUERY_COLLECTION_NUM_ERROR.getDescription());\n    throw new TypesenseConnectorException(QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription());\n}\n// after\n} catch (Exception e) {\n    log.error(\"query collection doc num failed, collection={}\", collection, e);\n    throw new TypesenseConnectorException(QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription(), e);\n}","handlingStrategy":"try-catch","validationCode":"// verify collection is reachable before counting\nCollectionsResponse cols = client.collections().get();\nboolean exists = cols.stream().anyMatch(c -> c.getName().equals(collection));","typeGuard":null,"tryCatchPattern":"try {\n    long n = client.collectionDocNum(collection);\n} catch (TypesenseConnectorException e) {\n    if (e.getErrorCode() == QUERY_COLLECTION_NUM_ERROR) { /* check auth/connectivity, retry */ }\n}","preventionTips":["Use a Typesense API key with search permission on the target collection.","Verify collection name spelling against GET /collections.","Prefer the collection metadata endpoint when only a count is needed."],"tags":["typesense","http","search-query"],"backgroundTag":"database-query-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}