{"record":{"id":"f70928df7703a84a","repo":"weaviate/weaviate","slug":"using-s-to-filter-by-timestamp-must-use-val","errorCode":null,"errorMessage":"using [\"%s\"] to filter by timestamp: must use \"valueText\" or \"valueDate\"","messagePattern":"using \\[\"(.+?)\"\\] to filter by timestamp: must use \"valueText\" or \"valueDate\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"entities/filters/filters_validator.go","lineNumber":221,"sourceCode":"\t\treturn true\n\tdefault:\n\t\treturn false\n\t}\n}\n\nfunc validateInternalPropertyClause(propName schema.PropertyName, cw *clauseWrapper) error {\n\tswitch propName {\n\tcase InternalPropBackwardsCompatID, InternalPropID:\n\t\tif cw.isType(schema.DataTypeText) {\n\t\t\treturn nil\n\t\t}\n\t\treturn errors.Errorf(\n\t\t\t`using [\"_id\"] to filter by uuid: must use \"valueText\" to specify the id`)\n\tcase InternalPropCreationTimeUnix, InternalPropLastUpdateTimeUnix:\n\t\tif cw.isType(schema.DataTypeDate) || cw.isType(schema.DataTypeText) {\n\t\t\treturn nil\n\t\t}\n\t\treturn errors.Errorf(\n\t\t\t`using [\"%s\"] to filter by timestamp: must use \"valueText\" or \"valueDate\"`, propName)\n\tdefault:\n\t\treturn errors.Errorf(\"unsupported internal property: %s\", propName)\n\t}\n}\n\nfunc isUUIDType(dtString string) bool {\n\tdt := schema.DataType(dtString)\n\treturn dt == schema.DataTypeUUID || dt == schema.DataTypeUUIDArray\n}\n\nfunc validateUUIDType(propName schema.PropertyName, cw *clauseWrapper) error {\n\tif cw.isType(schema.DataTypeText) {\n\t\treturn validateUUIDOperators(propName, cw)\n\t}\n\n\treturn fmt.Errorf(\"property %q is of type \\\"uuid\\\" or \\\"uuid[]\\\": \"+\n\t\t\"specify uuid as string using \\\"valueText\\\"\", propName)","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/entities/filters/filters_validator.go#L203-L239","documentation":"The internal timestamp properties (creationTimeUnix, lastUpdateTimeUnix) accept only valueDate or valueText filter values. Any other value kind (e.g. valueInt for the unix epoch) is rejected by the filter validator.","triggerScenarios":"Filtering with path [\"_creationTimeUnix\"] or [\"_lastUpdateTimeUnix\"] using valueInt/valueNumber with a numeric epoch instead of valueDate (ISO 8601 / unix per API) or valueText.","commonSituations":"Developers assume timestamps are integers because the name says 'Unix' and send valueInt; auto-generated clients mapping meta fields to numbers.","solutions":["Switch the filter to valueDate with an ISO 8601 date string (or valueText).","Do not use valueInt for internal timestamp filters.","Wrap internal-meta filter construction in a helper that emits valueDate."],"exampleFix":"// before\n{ path: [\"_creationTimeUnix\"], valueInt: 1699999999, operator: GreaterThan }\n// after\n{ path: [\"_creationTimeUnix\"], valueDate: \"2023-11-14T00:00:00Z\", operator: GreaterThan }","handlingStrategy":"validation","validationCode":"function checkTimestampFilter(f) {\n  const p = f.path?.[0];\n  if (p === '_creationTimeUnix' || p === '_lastUpdateTimeUnix') {\n    if (f.valueDate === undefined && f.valueText === undefined) {\n      throw new Error(`${p} filters require valueDate or valueText, not numeric kinds`);\n    }\n  }\n}","typeGuard":"const isInternalTimestampPath = (path) => ['_creationTimeUnix','_lastUpdateTimeUnix'].includes(path?.[0]);","tryCatchPattern":null,"preventionTips":["Use valueDate (ISO 8601) for internal timestamp filters, never valueInt","Build meta-field filters through a dedicated helper","Read the field name as a label, not as a hint about the wire type"],"tags":["weaviate","filters","timestamps","validation"],"backgroundTag":"filter-value-type-mismatch","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}