{"record":{"id":"78fcc2c587dca481","repo":"apache/beam","slug":"beam-logical-type-timestamp-v1-requires-a-precision-argument","errorCode":null,"errorMessage":"beam:logical_type:timestamp:v1 requires a precision argument.","messagePattern":"beam:logical_type:timestamp:v1 requires a precision argument\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/schemas.py","lineNumber":1032,"sourceCode":"  represent the fraction of a second, e.g. 3 for milliseconds, 6 for\n  microseconds, 9 for nanoseconds.\n\n  Values are represented as a row of ``seconds`` (INT64, floored seconds\n  since the epoch) and ``subseconds`` (units of 10**-precision seconds,\n  always in ``[0, 10**precision)``.\n  ``subseconds`` is an INT16 field for precision < 5 and an INT32\n  field otherwise.\n\n  Note: Timestamp originating from Python to xlang still defaults to\n  MicrosInstant for backwards compatibility. To override the mapping of\n  Timestamp to this logical type, re-register using\n  :func:`~LogicalType.register_logical_type(ParameterizedTimestamp)`.\n  \"\"\"\n  def __init__(self, precision: Optional[int] = None) -> None:\n    if precision is None:\n      # A timestamp:v1 proto without its precision argument is malformed;\n      # decoding at a guessed precision would silently misscale subseconds.\n      raise ValueError(\n          'beam:logical_type:timestamp:v1 requires a precision argument.')\n    # The argument arrives as np.int32 when decoded from a schema proto.\n    precision = int(precision)\n    if not 0 <= precision <= Timestamp.NANOS_PRECISION:\n      raise ValueError(\n          'Timestamp precision must be between 0 and %d (inclusive), '\n          'but was %d.' % (Timestamp.NANOS_PRECISION, precision))\n    self._precision = precision\n\n  @classmethod\n  def urn(cls):\n    return common_urns.timestamp.urn\n\n  def representation_type(self) -> type:  # type: ignore[override]\n    # Unlike other logical types, the representation depends on the\n    # argument, so this is an instance method rather than a classmethod.\n    if self._precision < _TIMESTAMP_SHORT_PRECISION_LIMIT:\n      return ParameterizedTimestampShortRepresentation","sourceCodeStart":1014,"sourceCodeEnd":1050,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/schemas.py#L1014-L1050","documentation":"ParameterizedTimestamp (beam:logical_type:timestamp:v1) requires an explicit precision argument; constructing it with precision=None raises ValueError. A timestamp:v1 proto without its precision argument is considered malformed, since decoding at a guessed precision would silently misscale subseconds.","triggerScenarios":"Instantiating ParameterizedTimestamp() or ParameterizedTimestamp(None); decoding a logical_type proto whose argument/argument_type fields are missing so the constructor is called with no precision.","commonSituations":"Hand-building schema protos for timestamp logical types and forgetting the argument; a runner or older SDK emitting timestamp:v1 without precision; tests constructing the class directly.","solutions":["Pass an explicit precision (0-9) when constructing ParameterizedTimestamp, e.g. ParameterizedTimestamp(precision=6).","Ensure the schema proto includes both argument_type and argument for the timestamp logical type before decoding.","Use plain Timestamp/NanosDuration types instead of the parameterized logical type if no precision is needed."],"exampleFix":"// before\nlt = ParameterizedTimestamp()  # ValueError\n\n// after\nlt = ParameterizedTimestamp(precision=6)  # microseconds","handlingStrategy":"validation","validationCode":"def build_parameterized_timestamp(precision):\n    if precision is None:\n        raise ValueError(\"precision is required for beam:logical_type:timestamp:v1\")\n    return ParameterizedTimestamp(precision=int(precision))","typeGuard":null,"tryCatchPattern":"try:\n    lt = ParameterizedTimestamp(precision)\nexcept ValueError:\n    lt = ParameterizedTimestamp(precision=6)  # default to micros if proto lacked precision","preventionTips":["Always pass precision explicitly when constructing ParameterizedTimestamp.","Ensure schema protos carry both argument_type and argument for timestamp logical types.","Document the precision used by your pipeline so readers can reconstruct it."],"tags":["python","apache-beam","timestamp","logical-type","precision"],"backgroundTag":"missing-required-argument","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"}