{"record":{"id":"062d8adf127a428a","repo":"apache/hadoop","slug":"seeking-in-unsorted-tfile","errorCode":null,"errorMessage":"Seeking in unsorted TFile","messagePattern":"Seeking in unsorted TFile","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java","lineNumber":998,"sourceCode":"    }\n\n    /**\n     * if greater is true then returns the beginning location of the block\n     * containing the key strictly greater than input key. if greater is false\n     * then returns the beginning location of the block greater than equal to\n     * the input key\n     * \n     * @param key\n     *          the input key\n     * @param greater\n     *          boolean flag\n     * @return\n     * @throws IOException\n     */\n    Location getBlockContainsKey(RawComparable key, boolean greater)\n        throws IOException {\n      if (!isSorted()) {\n        throw new RuntimeException(\"Seeking in unsorted TFile\");\n      }\n      checkTFileDataIndex();\n      int blkIndex =\n          (greater) ? tfileIndex.upperBound(key) : tfileIndex.lowerBound(key);\n      if (blkIndex < 0) return end;\n      return new Location(blkIndex, 0);\n    }\n\n    Location getLocationByRecordNum(long recNum) throws IOException {\n      checkTFileDataIndex();\n      return tfileIndex.getLocationByRecordNum(recNum);\n    }\n\n    long getRecordNumByLocation(Location location) throws IOException {\n      checkTFileDataIndex();\n      return tfileIndex.getRecordNumByLocation(location);      \n    }\n    ","sourceCodeStart":980,"sourceCodeEnd":1016,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java#L980-L1016","documentation":"Thrown by TFile.Reader.getBlockContainsKey(RawComparable, boolean) when a key-based seek is attempted on an unsorted TFile. Binary search over the block index requires sorted keys and a stored comparator; unsorted files have neither, so seeking by key is impossible and rejected with RuntimeException. The method backs reader/scanner lookups such as lowerBound/upperBound-style navigation.","triggerScenarios":"Calling scanner.seekTo(key, 0, key.length) or reader APIs that locate a key's block on a file written with a null comparator.","commonSituations":"Point lookups (get by key) against a file produced by an unsorted writer; switching ingestion from sorted to unsorted while read paths still do seeks; testing seek code against unsorted fixtures.","solutions":["Rewrite the TFile in sorted mode (pass a comparator name to TFile.Writer) so key-based seeking is possible","For unsorted files, scan sequentially with Scanner.advance() and filter keys in application code","Check reader.isSorted() before any key seek and choose the sequential path automatically"],"exampleFix":"// before\nScanner scanner = reader.createScanner();\nscanner.seekTo(key, 0, key.length); // RuntimeException: unsorted TFile\n\n// after\nScanner scanner = reader.createScanner();\nif (reader.isSorted()) {\n  scanner.seekTo(key, 0, key.length);\n} else {\n  while (scanner.advance()) { /* compare scanner.entry().getKey() yourself */ }\n}","handlingStrategy":"validation","validationCode":"if (!reader.isSorted()) {\n  // key seek impossible: scan sequentially instead\n  Scanner s = reader.createScanner();\n  while (s.advance()) { /* match keys yourself */ }\n} else {\n  Scanner s = reader.createScanner();\n  s.seekTo(key, 0, key.length);\n}","typeGuard":"static boolean supportsKeySeek(TFile.Reader reader) {\n  return reader.isSorted();\n}","tryCatchPattern":"catch (RuntimeException e) {\n  if (\"Seeking in unsorted TFile\".equals(e.getMessage())) {\n    // switch this read path to a full sequential scan\n  }\n}","preventionTips":["Write sorted TFiles whenever read patterns include point lookups or range seeks","Gate seek APIs behind an isSorted() check in your data-access layer","Include an unsorted fixture in tests to verify the sequential fallback path"],"tags":["hadoop","tfile","unsorted","seek","reader"],"backgroundTag":"requires-sorted-input","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}