docs/topics/impala_date.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="date" rev="2.0.0">

  <title>DATE Data Type</title>

  <titlealts audience="PDF">

    <navtitle>DATE</navtitle>

  </titlealts>

  <prolog>
    <metadata>
      <data name="Category" value="Impala"/>
      <data name="Category" value="Impala Data Types"/>
      <data name="Category" value="SQL"/>
      <data name="Category" value="Data Analysts"/>
      <data name="Category" value="Developers"/>
      <data name="Category" value="Dates and Times"/>
    </metadata>
  </prolog>

  <conbody>

    <p> Use the <codeph>DATE</codeph> data type to store date values. The
        <codeph>DATE</codeph> type is supported for HBase, Text, Avro, and
      Parquet. </p>

    <p>
      <b>Range:</b>
    </p>

    <p> 0001-01-01 to 9999-12-31 </p>

    <p>
      <b>Literals and expressions:</b>
    </p>

    <p> The <codeph>DATE</codeph> literals are in the form of
        <codeph>DATE'YYYY-MM-DD'</codeph>. For examplep, <codeph>DATE
        '2013-01-01'</codeph>
    </p>

    <p>
      <b>Parquet and Avro considerations:</b>
    </p>

    <p> Parquet and Avro use <codeph>DATE</codeph> logical type for dates. The
        <codeph>DATE</codeph> logical type annotates an <codeph>INT32</codeph>
      that stores the number of days from the Unix epoch, January 1, 1970. This
      representation introduces an interoperability issue between Impala and
      older versions of Hive: </p>

    <p> If Hive versions lower than 3.1 wrote dates earlier than 1582-10-15 to a
      Parquet or Avro table, those dates would be read back incorrectly by
      Impala and vice versa. In Hive 3.1 and higher, this is no longer an issue. </p>

    <p>
      <b>Explicit casting between DATE and other data types:</b>
    </p>

    <p>
      <codeph>DATE</codeph> type can only be converted to/from <codeph>DATE</codeph>,
      <codeph>TIMESTAMP</codeph>, or <codeph>STRING</codeph> types as described below.
    </p>

    <table id="table_ovw_zt1_p3b">
      <tgroup cols="3">
        <colspec colnum="1" colname="col1" colwidth="1*"/>
        <colspec colname="newCol2" colnum="2" colwidth="1.09*"/>
        <colspec colnum="3" colname="col2" colwidth="3.46*"/>
        <thead>
          <row>
            <entry>
              Cast from
            </entry>
            <entry>
              Cast to
            </entry>
            <entry>
              Result
            </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              <codeph>TIMESTAMP</codeph>
            </entry>
            <entry>
              <codeph>DATE</codeph>
            </entry>
            <entry>
              The date component of the <codeph>TIMESTAMP</codeph> is returned, and the time of
              the day component of the <codeph>TIMESTAMP</codeph> is ignored.
            </entry>
          </row>
          <row>
            <entry>
              <codeph>STRING</codeph>
            </entry>
            <entry>
              <codeph>DATE</codeph>
            </entry>
            <entry>
              The <codeph>DATE</codeph> value of <codeph>yyyy-MM-dd</codeph> is returned.

              <p>
                The <codeph>STRING</codeph> value must be in the <codeph>yyyy-MM-dd</codeph> or
                <codeph>yyyy-MM-dd HH:mm:ss.SSSSSSSSS</codeph> pattern.
              </p>



              <p>
                If the time component is present in <codeph>STRING</codeph>, it is silently
                ignored.
              </p>



              <p>
                If the <codeph>STRING</codeph> value does not match the above formats, an error
                is returned.
              </p>
            </entry>
          </row>
          <row>
            <entry>
              <codeph>DATE</codeph>
            </entry>
            <entry>
              <codeph>TIMESTAMP</codeph>
            </entry>
            <entry>
              The year, month, and day of the <codeph>DATE</codeph> is returned along with the
              time of day component set to <codeph>00:00:00</codeph>.
            </entry>
          </row>
          <row>
            <entry>
              <codeph>DATE</codeph>
            </entry>
            <entry>
              <codeph>STRING</codeph>
            </entry>
            <entry>
              The <codeph>STRING</codeph> value, <codeph>'yyyy-MM-dd'</codeph>, is returned.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <p>
      <b>Implicit casting between DATE and other types: </b>
    </p>

    <p>
      Implicit casting is supported:
    </p>

    <ul>
      <li>
        From <codeph>STRING</codeph> to <codeph>DATE</codeph> if the source
        <codeph>STRING</codeph> value is in the <codeph>yyyy-MM-dd</codeph> or
        <codeph>yyyy-MM-dd HH:mm:ss.SSSSSSSSS</codeph> pattern.
      </li>

      <li>
        From <codeph>DATE</codeph> to <codeph>TIMESTAMP</codeph>.
      </li>
    </ul>

    <p>
      <b>Added in:</b>
    </p>

    <p>
      The <codeph>DATE</codeph> type is available in Impala 3.3 and higher.
    </p>

  </conbody>

</concept>