[PECOBLR-427] Add INTERVAL Type support (#835)

* init changes

* update error message

* update error message

* added unit tests

* return only body in toLiteral

* edge case

* handle edge case

* add logging for edge case

* correct getColumn() output for interval type

* added fake service test

* address comment

* added a TODO

* removed unused constants

Author: shivam2680

src/main/java/com/databricks/jdbc/api/impl/DatabricksResultSet.java

@@ -487,6 +487,7 @@ public Object getObject(int columnIndex) throws SQLException {
         || columnTypeName.startsWith(STRUCT)) {
       return handleComplexDataTypes(obj, columnTypeName);
     }
+    // TODO: Add separate handling for INTERVAL JSON_ARRAY result format.
     return ConverterHelper.convertSqlTypeToJavaType(columnType, obj);
   }
 

src/main/java/com/databricks/jdbc/api/impl/converters/ArrowToJavaObjectConverter.java

@@ -125,6 +125,15 @@ public static Object convert(
           timeZone = Optional.of(((TimeStampMicroTZVector) columnVector).getTimeZone());
         }
         return convertToTimestamp(object, timeZone);
+      case INTERVAL:
+        if (arrowMetadata == null) {
+          String errorMessage =
+              String.format("Failed to read INTERVAL %s with null metadata.", object);
+          LOGGER.error(errorMessage);
+          throw new DatabricksValidationException(errorMessage);
+        }
+        IntervalConverter ic = new IntervalConverter(arrowMetadata);
+        return ic.toLiteral(object);
       case NULL:
         return null;
       default:

src/main/java/com/databricks/jdbc/api/impl/converters/IntervalConverter.java

@@ -0,0 +1,113 @@
+package com.databricks.jdbc.api.impl.converters;
+
+import com.databricks.jdbc.log.JdbcLogger;
+import com.databricks.jdbc.log.JdbcLoggerFactory;
+import java.time.Duration;
+import java.time.Period;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Converts a java.time.Period or java.time.Duration into the exact ANSI‐style interval literals
+ * that Databricks prints.
+ */
+public class IntervalConverter {
+
+  private static final JdbcLogger LOGGER = JdbcLoggerFactory.getLogger(IntervalConverter.class);
+
+  // Arrow stores day‐time intervals in microseconds. Converting to nanoseconds to align with Thrift
+  private static final long NANOS_PER_SECOND = 1_000_000_000L;
+  private static final long NANOS_PER_MINUTE = NANOS_PER_SECOND * 60;
+  private static final long NANOS_PER_HOUR = NANOS_PER_MINUTE * 60;
+  private static final long NANOS_PER_DAY = NANOS_PER_HOUR * 24;
+
+  private static final Pattern INTERVAL_PATTERN =
+      Pattern.compile("INTERVAL\\s+(\\w+)(?:\\s+TO\\s+(\\w+))?", Pattern.CASE_INSENSITIVE);
+
+  /** The supported fields in the SQL syntax. */
+  public enum Field {
+    YEAR,
+    MONTH,
+    DAY,
+    HOUR,
+    MINUTE,
+    SECOND
+  }
+
+  private final boolean isYearMonth;
+
+  /**
+   * @param arrowMetadata e.g. "INTERVAL YEAR TO MONTH" or "INTERVAL HOUR TO SECOND"
+   */
+  public IntervalConverter(String arrowMetadata) {
+    Matcher m = INTERVAL_PATTERN.matcher(arrowMetadata.trim());
+    if (!m.matches()) {
+      throw new IllegalArgumentException("Invalid interval metadata: " + arrowMetadata);
+    }
+    Field start = Field.valueOf(m.group(1).toUpperCase());
+    // YEAR or MONTH qualifiers → Period; otherwise → Duration
+    this.isYearMonth = (start.equals(Field.YEAR) || start.equals(Field.MONTH));
+  }
+
+  /**
+   * Turn a Period (YEAR/MONTH intervals) or Duration (DAY–TIME intervals) into exactly the string
+   * Databricks will print.
+   */
+  public String toLiteral(Object obj) {
+    String body;
+    if (isYearMonth) {
+      if (!(obj instanceof Period)) {
+        throw new IllegalArgumentException("Expected Period, got " + obj.getClass());
+      }
+      body = formatYearMonth((Period) obj);
+    } else {
+      if (!(obj instanceof Duration)) {
+        throw new IllegalArgumentException("Expected Duration, got " + obj.getClass());
+      }
+      body = formatFullDayTime((Duration) obj);
+    }
+    return body;
+  }
+
+  // --- YEAR–MONTH formatting ---
+  private String formatYearMonth(Period p) {
+    long totalMonths = p.getYears() * 12L + p.getMonths();
+    boolean neg = totalMonths < 0;
+    long absMonths = Math.abs(totalMonths);
+    long years = absMonths / 12;
+    long months = absMonths % 12;
+    // Databricks shows "Y-M" with no zero‐padding
+    String body = years + "-" + months;
+    return (neg ? "-" : "") + body;
+  }
+
+  // DAY–TIME always prints all subfields in D HH:MM:SS.NNNNNNNNN
+  // max day to second supported is 106751 23:47:16.854775. Beyond that Duration Object rolls over
+  // to LONG_MIN and loses info.
+  private String formatFullDayTime(Duration d) {
+    long nanos = d.toNanos();
+    if (nanos == Long.MIN_VALUE) {
+      nanos += 1; // -abs(LONG.MAX_VALUE)
+    }
+    boolean neg = nanos < 0;
+    if (neg) nanos = -nanos;
+
+    if (nanos == Long.MAX_VALUE) {
+      LOGGER.warn(
+          "Duration value at Long.MAX_VALUE detected - interval representation may be incorrect due to overflow");
+    }
+
+    long days = nanos / NANOS_PER_DAY;
+    nanos %= NANOS_PER_DAY;
+    long hours = nanos / NANOS_PER_HOUR;
+    nanos %= NANOS_PER_HOUR;
+    long minutes = nanos / NANOS_PER_MINUTE;
+    nanos %= NANOS_PER_MINUTE;
+    long seconds = nanos / NANOS_PER_SECOND;
+    long frac = nanos % NANOS_PER_SECOND;
+
+    // "%02d" for HH,MM,SS and "%09d" for nanosecond fraction
+    return String.format(
+        "%s%d %02d:%02d:%02d.%09d", neg ? "-" : "", days, hours, minutes, seconds, frac);
+  }
+}

src/main/java/com/databricks/jdbc/common/util/DatabricksTypeUtil.java

@@ -54,6 +54,7 @@ public class DatabricksTypeUtil {
   public static final String STRUCT = "STRUCT";
   public static final String VARIANT = "VARIANT";
   public static final String CHAR = "CHAR";
+  public static final String INTERVAL = "INTERVAL";
   private static final ArrayList<ColumnInfoTypeName> SIGNED_TYPES =
       new ArrayList<>(
           Arrays.asList(

src/main/java/com/databricks/jdbc/dbclient/impl/common/MetadataResultSetBuilder.java

@@ -1,6 +1,7 @@
 package com.databricks.jdbc.dbclient.impl.common;
 
 import static com.databricks.jdbc.common.MetadataResultConstants.*;
+import static com.databricks.jdbc.common.util.DatabricksTypeUtil.INTERVAL;
 import static com.databricks.jdbc.dbclient.impl.common.CommandConstants.*;
 import static com.databricks.jdbc.dbclient.impl.common.TypeValConstants.*;
 
@@ -322,7 +323,7 @@ int extractPrecision(String typeVal) {
   }
 
   int getColumnSize(String typeVal) {
-    if (typeVal == null || typeVal.isEmpty()) {
+    if (typeVal == null || typeVal.isEmpty() || typeVal.contains(INTERVAL)) {
       return 0;
     }
     int sizeFromTypeVal = getSizeFromTypeVal(typeVal);
@@ -500,6 +501,9 @@ int getCode(String s) {
       case "VARIANT":
         return 1111;
     }
+    if (s.startsWith(INTERVAL)) {
+      return 12;
+    }
     return 0;
   }
 

src/main/java/com/databricks/jdbc/dbclient/impl/sqlexec/ResultConstants.java

@@ -455,6 +455,26 @@ public class ResultConstants {
               Types.TIMESTAMP,
               3,
               null
+            },
+            {
+              "INTERVAL",
+              Types.VARCHAR,
+              40,
+              "'",
+              "'",
+              "Qualifier",
+              typeNullable,
+              false,
+              typeSearchable,
+              null,
+              false,
+              null,
+              "INTERVAL",
+              0,
+              6,
+              Types.VARCHAR,
+              null,
+              null
             }
           },
           StatementType.METADATA);

src/test/java/com/databricks/jdbc/api/impl/converters/ArrowToJavaObjectConverterTest.java

@@ -35,6 +35,42 @@ public class ArrowToJavaObjectConverterTest {
     this.bufferAllocator = new RootAllocator();
   }
 
+  @Test
+  public void testConvert_Interval() throws SQLException {
+    // 1200 months → "100-0"
+    IntervalYearVector yv = new IntervalYearVector("iv", bufferAllocator);
+    yv.allocateNewSafe();
+    yv.setSafe(0, 1200);
+    yv.setValueCount(1);
+
+    Object out =
+        ArrowToJavaObjectConverter.convert(
+            yv, 0, ColumnInfoTypeName.INTERVAL, "INTERVAL YEAR TO MONTH");
+    assertEquals("100-0", out);
+
+    // build a Duration of 200h13m50.3s → -200:13:50.3
+    IntervalDayVector dv = new IntervalDayVector("dv", bufferAllocator);
+    dv.allocateNewSafe();
+    // Arrow’s IntervalDayVector takes (days, milliseconds)
+    Duration d = Duration.ofHours(200).plusMinutes(13).plusSeconds(50).plusMillis(300);
+    long days = d.toDays();
+    int millis = (int) (d.minusDays(days).toMillis());
+    dv.setSafe(0, (int) days, millis);
+    dv.setValueCount(1);
+
+    out =
+        ArrowToJavaObjectConverter.convert(
+            dv, 0, ColumnInfoTypeName.INTERVAL, "INTERVAL HOUR TO SECOND");
+    assertEquals("8 08:13:50.300000000", out);
+
+    // null metadata throws DatabricksValidation Exception
+    assertThrows(
+        DatabricksValidationException.class,
+        () -> {
+          ArrowToJavaObjectConverter.convert(dv, 0, ColumnInfoTypeName.INTERVAL, null);
+        });
+  }
+
   @Test
   public void testNullObjectConversion() throws SQLException {
     TinyIntVector tinyIntVector = new TinyIntVector("tinyIntVector", this.bufferAllocator);

src/test/java/com/databricks/jdbc/api/impl/converters/IntervalConverterTest.java

@@ -0,0 +1,144 @@
+package com.databricks.jdbc.api.impl.converters;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.time.Duration;
+import java.time.Period;
+import java.time.temporal.ChronoUnit;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+@DisplayName("IntervalConverter")
+class IntervalConverterTest {
+
+  @Nested
+  @DisplayName("Year–Month intervals")
+  class YearMonth {
+
+    @ParameterizedTest(name = "[{index}] {1} of {0} months ⇒ “{2}”")
+    @CsvSource({
+      "1200, INTERVAL YEAR,          100-0",
+      "1200, INTERVAL MONTH,         100-0",
+      "1200, INTERVAL YEAR TO MONTH, 100-0",
+      "14,   INTERVAL YEAR TO MONTH, 1-2",
+      "-14,  INTERVAL YEAR TO MONTH, -1-2",
+      "0,    INTERVAL YEAR,          0-0",
+      "0,    INTERVAL MONTH,         0-0"
+    })
+    void testNormalization(long totalMonths, String meta, String expected) {
+      Period p = Period.ofMonths((int) totalMonths);
+      IntervalConverter ic = new IntervalConverter(meta);
+      assertEquals(expected, ic.toLiteral(p));
+    }
+
+    @Test
+    @DisplayName("Huge period still normalizes correctly")
+    void testHugePeriod() {
+      Period p = Period.ofYears(37212).plusMonths(11);
+      IntervalConverter ic = new IntervalConverter("INTERVAL YEAR TO MONTH");
+      assertEquals("37212-11", ic.toLiteral(p));
+    }
+
+    @Test
+    @DisplayName("Passing Duration to YEAR qualifier throws")
+    void testTypeMismatch() {
+      IntervalConverter ic = new IntervalConverter("INTERVAL YEAR");
+      assertThrows(IllegalArgumentException.class, () -> ic.toLiteral(Duration.ofHours(5)));
+    }
+  }
+
+  @Nested
+  @DisplayName("Day–Time intervals (full D HH:MM:SS.NNNNNNNNN form)")
+  class DayTime {
+
+    @ParameterizedTest(name = "[{index}] {0} ⇒ “{3}”")
+    @CsvSource({
+      // desc                   , metadata              , ISO8601           , expected
+      "zero                   , INTERVAL DAY TO SECOND, PT0S               , 0 00:00:00.000000000",
+      "only days              , INTERVAL DAY,          P3D                 , 3 00:00:00.000000000",
+      "days+hours             , INTERVAL DAY TO HOUR,  P2DT5H              , 2 05:00:00.000000000",
+      "days+minutes           , INTERVAL DAY TO MINUTE,P1DT2H30M           , 1 02:30:00.000000000",
+      "days+seconds frac      , INTERVAL DAY TO SECOND,P0DT0H0M4.005S      , 0 00:00:04.005000000",
+      "only hours             , INTERVAL HOUR,         PT27H               , 1 03:00:00.000000000",
+      "hour+minute            , INTERVAL HOUR TO MINUTE,PT2H5M             , 0 02:05:00.000000000",
+      "hour+second frac       , INTERVAL HOUR TO SECOND,PT1H0M0.123S       , 0 01:00:00.123000000",
+      "only minutes           , INTERVAL MINUTE,       PT125M              , 0 02:05:00.000000000",
+      "minute+second frac     , INTERVAL MINUTE TO SECOND,PT1M30.5S        , 0 00:01:30.500000000",
+      "only seconds frac      , INTERVAL SECOND,       PT45.789S           , 0 00:00:45.789000000",
+      "large nano fraction    , INTERVAL SECOND,       PT0.000000123S      , 0 00:00:00.000000123"
+    })
+    void testCanonicalForm(String desc, String meta, String iso, String expected) {
+      Duration d = Duration.parse(iso);
+      IntervalConverter ic = new IntervalConverter(meta);
+      assertEquals(expected, ic.toLiteral(d), () -> desc + " failed");
+    }
+
+    @Test
+    @DisplayName("Negative duration rollover across days")
+    void testNegativeAndRollover() {
+      // -(49h + 10m + 5s + 123ms)
+      Duration d =
+          Duration.ofHours(-49)
+              .plusMinutes(-10)
+              .plusSeconds(-5)
+              .plusMillis(-123)
+              .truncatedTo(ChronoUnit.MILLIS);
+      IntervalConverter ic = new IntervalConverter("INTERVAL DAY TO SECOND");
+      // |d| = 177005.123s → 2 days + 4205.123s → 2 days, 1h 10m 5.123s
+      assertEquals("-2 01:10:05.123000000", ic.toLiteral(d));
+    }
+
+    @Test
+    @DisplayName("Edge: just under one day")
+    void testMaxNanosUnderDay() {
+      long justUnder = Duration.ofDays(1).toNanos() - 1;
+      Duration d = Duration.ofNanos(justUnder);
+      IntervalConverter ic = new IntervalConverter("INTERVAL DAY TO SECOND");
+      assertEquals("0 23:59:59.999999999", ic.toLiteral(d));
+    }
+
+    @Test
+    @DisplayName("Very large duration formatting")
+    void testVeryLargeDuration() {
+      // 1000d + 12h + 34m + 56s + 789ns
+      Duration d =
+          Duration.ofDays(1000).plusHours(12).plusMinutes(34).plusSeconds(56).plusNanos(789);
+      IntervalConverter ic = new IntervalConverter("INTERVAL DAY TO SECOND");
+      assertEquals("1000 12:34:56.000000789", ic.toLiteral(d));
+    }
+
+    @Test
+    @DisplayName("LONG_MIN duration handling")
+    void testLongExtremesDuration() {
+      // LONG_MIN is -abs(LONG_MAX) + 1
+      Duration d = Duration.ofNanos(Long.MIN_VALUE);
+      IntervalConverter ic = new IntervalConverter("INTERVAL DAY TO SECOND");
+      assertEquals("-106751 23:47:16.854775807", ic.toLiteral(d));
+
+      // LONG_MAX
+      d = Duration.ofNanos(Long.MAX_VALUE);
+      ic = new IntervalConverter("INTERVAL DAY TO SECOND");
+      assertEquals("106751 23:47:16.854775807", ic.toLiteral(d));
+    }
+
+    @Test
+    @DisplayName("Passing Period to DAY qualifier throws")
+    void testDayMismatch() {
+      IntervalConverter ic = new IntervalConverter("INTERVAL HOUR TO MINUTE");
+      assertThrows(IllegalArgumentException.class, () -> ic.toLiteral(Period.ofDays(1)));
+    }
+  }
+
+  @Nested
+  @DisplayName("Error conditions")
+  class Errors {
+    @Test
+    @DisplayName("Invalid metadata string")
+    void testInvalidMetadata() {
+      assertThrows(IllegalArgumentException.class, () -> new IntervalConverter("NOT AN INTERVAL"));
+    }
+  }
+}