{"record":{"id":"17df477b810a63ef","repo":"temporalio/temporal","slug":"searchprecision-is-required-when-searching-for-a-s","errorCode":null,"errorMessage":"SearchPrecision is required when searching for a StartTime or CloseTime","messagePattern":"SearchPrecision is required when searching for a StartTime or CloseTime","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/archiver/gcloud/query_parser.go","lineNumber":72,"sourceCode":"}\n\nfunc (p *queryParser) Parse(query string) (*parsedQuery, error) {\n\tstmt, err := sqlparser.Parse(fmt.Sprintf(sqlquery.QueryTemplate, query))\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\twhereExpr := stmt.(*sqlparser.Select).Where.Expr\n\tparsedQuery := &parsedQuery{}\n\tif err := p.convertWhereExpr(whereExpr, parsedQuery); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif (parsedQuery.closeTime.IsZero() && parsedQuery.startTime.IsZero()) || (!parsedQuery.closeTime.IsZero() && !parsedQuery.startTime.IsZero()) {\n\t\treturn nil, errors.New(\"requires a StartTime or CloseTime\")\n\t}\n\n\tif parsedQuery.searchPrecision == nil {\n\t\treturn nil, errors.New(\"SearchPrecision is required when searching for a StartTime or CloseTime\")\n\t}\n\n\treturn parsedQuery, nil\n}\n\nfunc (p *queryParser) convertWhereExpr(expr sqlparser.Expr, parsedQuery *parsedQuery) error {\n\tif expr == nil {\n\t\treturn errors.New(\"where expression is nil\")\n\t}\n\n\tswitch expr := expr.(type) {\n\tcase *sqlparser.ComparisonExpr:\n\t\treturn p.convertComparisonExpr(expr, parsedQuery)\n\tcase *sqlparser.AndExpr:\n\t\treturn p.convertAndExpr(expr, parsedQuery)\n\tcase *sqlparser.ParenExpr:\n\t\treturn p.convertParenExpr(expr, parsedQuery)\n\tdefault:","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/archiver/gcloud/query_parser.go#L54-L90","documentation":"This error comes from the GCloud archive visibility query parser (common/archiver/gcloud/query_parser.go). When a workflow visibility query filters on StartTime or CloseTime, exactly one of those must be present AND a SearchPrecision (Day/Hour/Minute/Second) must also be supplied. The parser throws this when a time filter is present but SearchPrecision is missing, because the blobstore-based archiver needs the precision to bucket scans of time-partitioned objects.","triggerScenarios":"Calling gcloud.NewQueryParser().Parse(query) (or a GCloud visibility archiver that uses it) with a WHERE clause containing StartTime or CloseTime but no `SearchPrecision = \"Hour\"` (or Day/Minute/Second) condition. Parse runs the full SQL parse and where-expression conversion first, so the query must otherwise be valid to reach this check.","commonSituations":"Users running `temporal workflow list --query` against GCloud archival visibility with queries like `WHERE StartTime > '2024-01-01T00:00:00Z'` copied from Elasticsearch/SQL-style visibility examples that do not require SearchPrecision. Also happens when a query builder omits the precision clause or when upgrading from a visibility store that did not need it.","solutions":["Add a SearchPrecision condition to the WHERE clause, e.g. `SearchPrecision = \"Day\"`, alongside the single StartTime or CloseTime filter.","Ensure exactly one of StartTime or CloseTime is present; both missing or both present triggers the sibling \"requires a StartTime or CloseTime\" error first.","Use one of the supported precision values: Day, Hour, Minute, Second.","If this query is intended for Elasticsearch/SQL visibility, point it at that visibility store instead of the GCloud archival visibility store, which does not require SearchPrecision."],"exampleFix":"// before\nq := \"CloseTime BETWEEN '2024-01-01T00:00:00Z' AND '2024-01-02T00:00:00Z'\"\nparsed, err := gcloud.NewQueryParser().Parse(q)\n// error: SearchPrecision is required when searching for a StartTime or CloseTime\n\n// after\nq := \"CloseTime BETWEEN '2024-01-01T00:00:00Z' AND '2024-01-02T00:00:00Z' AND SearchPrecision = 'Day'\"\nparsed, err := gcloud.NewQueryParser().Parse(q)","handlingStrategy":"validation","validationCode":"func hasTimeWithoutPrecision(q string) bool {\n\tql := strings.ToLower(q)\n\thasTime := strings.Contains(ql, \"starttime\") || strings.Contains(ql, \"closetime\")\n\treturn hasTime && !strings.Contains(ql, \"searchprecision\")\n}\n// if hasTimeWithoutPrecision(query) { add `AND SearchPrecision = 'Day'` or reject }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair StartTime/CloseTime filters with exactly one SearchPrecision value (Day/Hour/Minute/Second).","Never include both StartTime and CloseTime without understanding exactly one is required.","Keep a canonical query template for gcloud archival visibility queries."],"tags":["archival","gcloud","query-parsing","visibility"],"backgroundTag":"missing-query-parameter","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}