{"record":{"id":"b407a8c5382eeb81","repo":"prestodb/presto","slug":"hive-table-bucketing-is-ignored","errorCode":"HIVE_TABLE_BUCKETING_IS_IGNORED","errorMessage":"Table bucketing is ignored. The virtual \"$bucket\" column cannot be referenced.","messagePattern":"Table bucketing is ignored\\. The virtual \"\\$bucket\" column cannot be referenced\\.","errorType":"error_code","errorClass":"PrestoException","httpStatus":null,"severity":"error","filePath":"presto-hive/src/main/java/com/facebook/presto/hive/HiveUtil.java","lineNumber":1031,"sourceCode":"    }\n\n    @Nullable\n    public static String columnExtraInfo(boolean partitionKey)\n    {\n        return partitionKey ? \"partition key\" : null;\n    }\n\n    public static Optional<String> getPrefilledColumnValue(HiveColumnHandle columnHandle, HivePartitionKey partitionKey, HiveFileSplit fileSplit, OptionalInt bucketNumber)\n    {\n        if (partitionKey != null) {\n            return partitionKey.getValue();\n        }\n        if (isPathColumnHandle(columnHandle)) {\n            return Optional.of(fileSplit.getPath());\n        }\n        if (isBucketColumnHandle(columnHandle)) {\n            if (!bucketNumber.isPresent()) {\n                throw new PrestoException(HIVE_TABLE_BUCKETING_IS_IGNORED, \"Table bucketing is ignored. The virtual \\\"$bucket\\\" column cannot be referenced.\");\n            }\n            return Optional.of(String.valueOf(bucketNumber.getAsInt()));\n        }\n        if (isFileSizeColumnHandle(columnHandle)) {\n            return Optional.of(String.valueOf(fileSplit.getFileSize()));\n        }\n        if (isFileModifiedTimeColumnHandle(columnHandle)) {\n            return Optional.of(String.valueOf(fileSplit.getFileModifiedTime()));\n        }\n        throw new PrestoException(NOT_SUPPORTED, \"unsupported hidden column: \" + columnHandle);\n    }\n\n    public static void closeWithSuppression(RecordCursor recordCursor, Throwable throwable)\n    {\n        requireNonNull(recordCursor, \"recordCursor is null\");\n        requireNonNull(throwable, \"throwable is null\");\n        try {\n            recordCursor.close();","sourceCodeStart":1013,"sourceCodeEnd":1049,"githubUrl":"https://github.com/prestodb/presto/blob/55bb57d202de3b926896fa966c2c4a44c779634e/presto-hive/src/main/java/com/facebook/presto/hive/HiveUtil.java#L1013-L1049","documentation":"Thrown when a query references the virtual \"$bucket\" column but the split has no bucket number available, meaning table bucketing is effectively ignored (e.g. no bucketing info or legacy/local mode where buckets aren't tracked). Presto cannot return the $bucket value without bucket context.","triggerScenarios":"SELECT \"$bucket\" FROM a Hive table in a context where bucketNumber is empty — e.g. the table/split was read without bucket tracking (bucketing ignored, unbucketed path, or a split source that doesn't populate bucket numbers).","commonSituations":"Queries against symlink/manifest or non-bucketed tables attempting \"$bucket\"; reads where bucketing validation was disabled; connector-internal reads that don't carry bucket ids.","solutions":["Remove \"$bucket\" from the SELECT list / predicates","Ensure the table is properly bucketed and read through a path that tracks bucket numbers (configured bucketing on the metastore table)","Recreate the table with CLUSTERED BY ... INTO n BUCKETS if it should be bucketed"],"exampleFix":"-- before\nSELECT \"$bucket\", * FROM db.t;\n-- after\nSELECT * FROM db.t;","handlingStrategy":"type-guard","validationCode":"-- verify the table is bucketed and query does not use \"$bucket\"\nSHOW CREATE TABLE db.t; -- CLUSTERED BY (...) INTO n BUCKETS must be present\ntableProps.getProperty(\"bucketing_version\");","typeGuard":"boolean canUseBucketColumn(String ddl) {\n    return ddl != null && ddl.contains(\"CLUSTERED BY\") && ddl.contains(\"BUCKETS\");\n}","tryCatchPattern":"try { rs = stmt.executeQuery(sql); }\ncatch (com.facebook.presto.spi.PrestoException e) {\n    if (e.getMessage().contains(\"$bucket\")) { /* drop $bucket from query or re-bucket table */ }\n    else throw e;\n}","preventionTips":["Do not reference \"$bucket\" unless the table is verified bucketed","Query DESCRIBE/SHOW CREATE to confirm CLUSTERED BY before using virtual bucket columns","Prefer filtering on real columns over virtual bucket columns"],"tags":["hive","bucketing","virtual-column"],"backgroundTag":"bucket-column-unavailable","analyzedSha":"55bb57d202de3b926896fa966c2c4a44c779634e","analyzedAt":"2026-09-04T12:50:26.162Z","contentChangedAt":"2026-09-04T12:50:26.162Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}