/*
 * 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.
 */

package org.apache.spark.sql.execution.command.v2

import org.apache.spark.sql.{AnalysisException, QueryTest, Row}
import org.apache.spark.sql.connector.catalog.TableCatalog
import org.apache.spark.sql.execution.command
import org.apache.spark.sql.internal.SQLConf
import org.apache.spark.sql.types.StringType
import org.apache.spark.util.Utils

/**
 * The class contains tests for the `DESCRIBE TABLE` command to check V2 table catalogs.
 */
class DescribeTableSuite extends command.DescribeTableSuiteBase
  with CommandSuiteBase {
  import testImplicits._

  test("DESCRIBE TABLE PARTITION on an existing partition") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = 1)")
      // Non-extended describe with a valid partition spec shows schema + partition section,
      // same output as DESCRIBE TABLE (partition spec is used only for validation).
      checkAnswer(
        sql(s"DESCRIBE TABLE $tbl PARTITION (id = 1)"),
        Seq(
          Row("id", "bigint", null),
          Row("data", "string", null),
          Row("# Partition Information", "", ""),
          Row("# col_name", "data_type", "comment"),
          Row("id", "bigint", null)))
    }
  }

  test("DESCRIBE TABLE EXTENDED PARTITION shows detailed partition information") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = 1)")
      val result = sql(s"DESCRIBE TABLE EXTENDED $tbl PARTITION (id = 1)").collect()
      val colNames = result.map(_.getString(0))
      // Must include the detailed partition section header
      assert(colNames.contains("# Detailed Partition Information"))
      // Must include the partition values row
      assert(result.exists(r =>
        r.getString(0) == "Partition Values" && r.getString(1) == "[id=1]"))
    }
  }

  test("DESCRIBE TABLE PARTITION on a non-existent partition raises an error") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      checkError(
        exception = intercept[AnalysisException] {
          sql(s"DESCRIBE TABLE $tbl PARTITION (id = 999)").collect()
        },
        condition = "PARTITIONS_NOT_FOUND",
        parameters = Map(
          "partitionList" -> "PARTITION (`id` = 999)",
          "tableName" -> "`ns`.`table`"))
    }
  }

  test("DESCRIBE TABLE PARTITION on a table without partition management raises an error") {
    withNamespaceAndTable("ns", "table", nonPartitionCatalog) { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing")
      val sqlText = s"DESCRIBE TABLE $tbl PARTITION (id = 1)"
      checkError(
        exception = intercept[AnalysisException] {
          sql(sqlText)
        },
        condition = "INVALID_PARTITION_OPERATION.PARTITION_MANAGEMENT_IS_UNSUPPORTED",
        parameters = Map("name" -> s"`$nonPartitionCatalog`.`ns`.`table`"),
        queryContext = Array(ExpectedContext(
          fragment = tbl,
          start = sqlText.indexOf(tbl),
          stop = sqlText.indexOf(tbl) + tbl.length - 1)))
    }
  }

  test("DESCRIBE TABLE PARTITION with partial partition spec raises an error") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, city string, data string) " +
        s"$defaultUsing PARTITIONED BY (id, city)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = 1, city = 'NYC')")
      checkError(
        exception = intercept[AnalysisException] {
          sql(s"DESCRIBE TABLE $tbl PARTITION (id = 1)")
        },
        condition = "_LEGACY_ERROR_TEMP_1232",
        parameters = Map(
          "specKeys" -> "id",
          "partitionColumnNames" -> "id, city",
          "tableName" -> s"`$catalog`.`ns`.`table`"))
    }
  }

  test("DESCRIBE TABLE PARTITION with case-insensitive partition column name") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = 1)")
      // Case-insensitive partition column name should normalize.
      checkAnswer(
        sql(s"DESCRIBE TABLE $tbl PARTITION (ID = 1)"),
        Seq(
          Row("id", "bigint", null),
          Row("data", "string", null),
          Row("# Partition Information", "", ""),
          Row("# col_name", "data_type", "comment"),
          Row("id", "bigint", null)))
    }
  }

  test("DESCRIBE TABLE PARTITION with unknown partition column raises an error") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      checkError(
        exception = intercept[AnalysisException] {
          sql(s"DESCRIBE TABLE $tbl PARTITION (xyz = 1)")
        },
        condition = "PARTITIONS_NOT_FOUND",
        parameters = Map(
          "partitionList" -> "`xyz`",
          "tableName" -> s"`$catalog`.`ns`.`table`"))
    }
  }

  test("DESCRIBE TABLE EXTENDED PARTITION with multi-column partition") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (data string, id bigint, city string) " +
        s"$defaultUsing PARTITIONED BY (id, city)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = 1, city = 'NYC')")
      val result = sql(s"DESCRIBE TABLE EXTENDED $tbl PARTITION (id = 1, city = 'NYC')").collect()
      assert(result.exists(r =>
        r.getString(0) == "Partition Values" && r.getString(1) == "[id=1, city=NYC]"))
    }
  }

  test("DESCRIBE TABLE EXTENDED PARTITION with NULL partition value") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing PARTITIONED BY (id)")
      sql(s"ALTER TABLE $tbl ADD PARTITION (id = null)")
      val result = sql(s"DESCRIBE TABLE EXTENDED $tbl PARTITION (id = null)").collect()
      val partRow = result.find(_.getString(0) == "Partition Values")
      assert(partRow.isDefined, s"Partition Values row not found in: ${result.mkString("\n")}")
      assert(partRow.get.getString(1) == "[id=NULL]",
        s"Unexpected partition value: ${partRow.get.getString(1)}")
    }
  }

  test("DESCRIBE TABLE of a partitioned table by nested columns") {
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (s struct<id:INT, a:BIGINT>, data string) " +
        s"$defaultUsing PARTITIONED BY (s.id, s.a)")
      val descriptionDf = sql(s"DESCRIBE TABLE $tbl")
      checkAnswer(
        descriptionDf.filter("col_name != 'Created Time'"),
        Seq(
          Row("data", "string", null),
          Row("s", "struct<id:int,a:bigint>", null),
          Row("# Partition Information", "", ""),
          Row("# col_name", "data_type", "comment"),
          Row("s.id", "int", null),
          Row("s.a", "bigint", null)))
    }
  }

  test("DESCRIBE TABLE EXTENDED of a partitioned table") {
    withNamespaceAndTable("ns", "table") { tbl =>
      spark.sql(s"CREATE TABLE $tbl (id bigint, data string) $defaultUsing" +
        " PARTITIONED BY (id)" +
        " TBLPROPERTIES ('bar'='baz')" +
        " COMMENT 'this is a test table'" +
        " LOCATION 'file:/tmp/testcat/table_name'")
      val descriptionDf = spark.sql(s"DESCRIBE TABLE EXTENDED $tbl")
      assert(descriptionDf.schema.map(field => (field.name, field.dataType)) === Seq(
        ("col_name", StringType),
        ("data_type", StringType),
        ("comment", StringType)))
      checkAnswer(
        descriptionDf,
        Seq(
          Row("id", "bigint", null),
          Row("data", "string", null),
          Row("# Partition Information", "", ""),
          Row("# col_name", "data_type", "comment"),
          Row("id", "bigint", null),
          Row("", "", ""),
          Row("# Metadata Columns", "", ""),
          Row("index", "int", "Metadata column used to conflict with a data column"),
          Row("_partition", "string", "Partition key used to store the row"),
          Row("", "", ""),
          Row("# Detailed Table Information", "", ""),
          Row("Catalog", catalog, ""),
          Row("Namespace", "ns", ""),
          Row("Database", "ns", ""),
          Row("Table", "table", ""),
          Row("Type", "MANAGED", ""),
          Row("Comment", "this is a test table", ""),
          Row("Location", "file:/tmp/testcat/table_name", ""),
          Row("Provider", "_", ""),
          Row(TableCatalog.PROP_OWNER.capitalize, Utils.getCurrentUserName(), ""),
          Row("Table Properties", "[bar=baz]", ""),
          Row("Statistics", "0 bytes, 0 rows", null)))
    }
  }

  test("DESCRIBE TABLE EXTENDED emits structured Catalog/Namespace/Table rows") {
    // Pin that DescribeTableExec emits the resolved-identifier components as separate
    // rows under the `# Detailed Table Information` block, so consumers can read each
    // part programmatically rather than splitting a concatenated identifier string. Also
    // pin that for a single-segment namespace, an additional `Database` row is emitted
    // alongside `Namespace` for v1 compatibility (mirroring v1 `CatalogTable` output).
    withNamespaceAndTable("ns", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint) $defaultUsing")
      val rows = sql(s"DESCRIBE TABLE EXTENDED $tbl").collect()
      def findRowValue(name: String): String = rows
        .find(_.getString(0) == name)
        .getOrElse(fail(s"DESCRIBE output missing the `$name` row"))
        .getString(1)
      assert(findRowValue("Catalog") == catalog)
      assert(findRowValue("Namespace") == "ns")
      assert(findRowValue("Database") == "ns",
        "single-segment namespace must also surface as a `Database` row for v1 parity")
      assert(findRowValue("Table") == "table")
    }
  }

  test("DESCRIBE TABLE EXTENDED with a multi-segment namespace surfaces the leaf " +
      "segment in `Database` and joins `Namespace` with dots") {
    // Multi-segment v2 namespaces still emit a `Database` row for v1 compatibility,
    // carrying the trailing namespace segment. `Namespace` carries the full dot-joined
    // form for consumers that need the complete path (with `quoteIfNeeded` applied per
    // segment -- not exercised here because both segments are valid bare identifiers).
    withNamespaceAndTable("ns1.ns2", "table") { tbl =>
      sql(s"CREATE TABLE $tbl (id bigint) $defaultUsing")
      val rows = sql(s"DESCRIBE TABLE EXTENDED $tbl").collect()
      val byName = rows.map(r => r.getString(0) -> r.getString(1)).toMap
      assert(byName.get("Catalog").contains(catalog))
      assert(byName.get("Namespace").contains("ns1.ns2"))
      assert(byName.get("Database").contains("ns2"),
        "multi-segment namespace must surface the trailing segment as `Database`")
      assert(byName.get("Table").contains("table"))
    }
  }

  test("describe a non-existent column") {
    withNamespaceAndTable("ns", "tbl") { tbl =>
      sql(s"""
        |CREATE TABLE $tbl
        |(key int COMMENT 'column_comment', col struct<x:int, y:string>)
        |$defaultUsing""".stripMargin)
      val query = s"DESC $tbl key1"
      checkError(
        exception = intercept[AnalysisException] {
          sql(query).collect()
        },
        condition = "UNRESOLVED_COLUMN.WITH_SUGGESTION",
        sqlState = "42703",
        parameters = Map(
          "objectName" -> "`key1`",
          "proposal" -> "`key`, `col`"),
        context = ExpectedContext(
          fragment = query,
          start = 0,
          stop = query.length -1)
      )
    }
  }

  test("describe a column in case insensitivity") {
    withSQLConf(SQLConf.CASE_SENSITIVE.key -> "false") {
      withNamespaceAndTable("ns", "tbl") { tbl =>
        sql(s"CREATE TABLE $tbl (key int COMMENT 'comment1') $defaultUsing")
        QueryTest.checkAnswer(
          sql(s"DESC $tbl KEY"),
          Seq(Row("col_name", "KEY"), Row("data_type", "int"), Row("comment", "comment1")))
      }
    }

    withSQLConf(SQLConf.CASE_SENSITIVE.key -> "true") {
      withNamespaceAndTable("ns", "tbl") { tbl =>
        sql(s"CREATE TABLE $tbl (key int COMMENT 'comment1') $defaultUsing")
        val query = s"DESC $tbl KEY"
        checkError(
          exception = intercept[AnalysisException] {
            sql(query).collect()
          },
          condition = "UNRESOLVED_COLUMN.WITH_SUGGESTION",
          sqlState = "42703",
          parameters = Map(
            "objectName" -> "`KEY`",
            "proposal" -> "`key`"),
          context = ExpectedContext(
            fragment = query,
            start = 0,
            stop = query.length - 1))
      }
    }
  }

  test("describe extended (formatted) a column") {
    withNamespaceAndTable("ns", "tbl") { tbl =>
      sql(s"""
        |CREATE TABLE $tbl
        |(key INT COMMENT 'column_comment', col STRING)
        |$defaultUsing""".stripMargin)

      sql(s"INSERT INTO $tbl values (1, 'aaa'), (2, 'bbb'), (3, 'ccc'), (null, 'ddd')")
      val descriptionDf = sql(s"DESCRIBE TABLE EXTENDED $tbl key")
      assert(descriptionDf.schema.map(field => (field.name, field.dataType)) === Seq(
        ("info_name", StringType),
        ("info_value", StringType)))
      checkAnswer(
        descriptionDf,
        Seq(
          Row("col_name", "key"),
          Row("data_type", "int"),
          Row("comment", "column_comment"),
          Row("min", "NULL"),
          Row("max", "NULL"),
          Row("num_nulls", "1"),
          Row("distinct_count", "4"),
          Row("avg_col_len", "NULL"),
          Row("max_col_len", "NULL")))
    }
  }

  test("SPARK-46535: describe extended (formatted) a column without col stats") {
    withNamespaceAndTable("ns", "tbl") { tbl =>
      sql(
        s"""
           |CREATE TABLE $tbl
           |(key INT COMMENT 'column_comment', col STRING)
           |$defaultUsing""".stripMargin)

      val descriptionDf = sql(s"DESCRIBE TABLE EXTENDED $tbl key")
      assert(descriptionDf.schema.map(field => (field.name, field.dataType)) === Seq(
        ("info_name", StringType),
        ("info_value", StringType)))
      checkAnswer(
        descriptionDf,
        Seq(
          Row("col_name", "key"),
          Row("data_type", "int"),
          Row("comment", "column_comment")))
    }
  }

  test("describe extended table with stats") {
    withNamespaceAndTable("ns", "tbl") { tbl =>
      sql(
        s"""
           |CREATE TABLE $tbl
           |(key INT, col STRING)
           |$defaultUsing""".stripMargin)

      sql(s"INSERT INTO $tbl values (1, 'aaa'), (2, 'bbb'), (3, 'ccc'), (null, 'ddd')")
      val descriptionDf = sql(s"DESCRIBE TABLE EXTENDED $tbl")
      val stats = descriptionDf.filter("col_name == 'Statistics'").head()
        .getAs[String]("data_type")
      assert("""\d+\s+bytes,\s+4\s+rows""".r.matches(stats))
    }
  }

  test("desc table constraints") {
    withNamespaceAndTable("ns", "pk_table", nonPartitionCatalog) { tbl =>
      withNamespaceAndTable("ns", "fk_table", nonPartitionCatalog) { fkTable =>
        sql(
          s"""
             |CREATE TABLE $fkTable (id INT PRIMARY KEY) $defaultUsing
        """.stripMargin)
        sql(
          s"""
             |CREATE TABLE $tbl (
             |  id INT,
             |  a INT,
             |  b STRING,
             |  c STRING,
             |  PRIMARY KEY (id),
             |  CONSTRAINT fk_a FOREIGN KEY (a) REFERENCES $fkTable(id) RELY,
             |  CONSTRAINT uk_b UNIQUE (b),
             |  CONSTRAINT uk_a_c UNIQUE (a, c),
             |  CONSTRAINT c1 CHECK (c IS NOT NULL),
             |  CONSTRAINT c2 CHECK (id > 0)
             |)
             |$defaultUsing
        """.stripMargin)

        // ENFORCED/NOT ENFORCED and RELY/NORELY are always emitted to match SHOW CREATE TABLE.
        var expectedConstraintsDdl = Array(
          "# Constraints,,",
          "pk_table_pk,PRIMARY KEY (id) NOT ENFORCED NORELY,",
          s"fk_a,FOREIGN KEY (a) REFERENCES $fkTable (id) NOT ENFORCED RELY,",
          "uk_b,UNIQUE (b) NOT ENFORCED NORELY,",
          "uk_a_c,UNIQUE (a, c) NOT ENFORCED NORELY,",
          "c1,CHECK (c IS NOT NULL) ENFORCED NORELY,",
          "c2,CHECK (id > 0) ENFORCED NORELY,"
        )
        var descDdL = sql(s"DESCRIBE EXTENDED $tbl").collect().map(_.mkString(","))
          .dropWhile(_ != "# Constraints,,")
        assert(descDdL === expectedConstraintsDdl)

        sql(s"ALTER TABLE $tbl ADD CONSTRAINT c3 CHECK (b IS NOT NULL) RELY")
        descDdL = sql(s"DESCRIBE EXTENDED $tbl").collect().map(_.mkString(","))
          .dropWhile(_ != "# Constraints,,")
        expectedConstraintsDdl = expectedConstraintsDdl ++
          Array("c3,CHECK (b IS NOT NULL) ENFORCED RELY,")
        assert(descDdL === expectedConstraintsDdl)

        sql(s"ALTER TABLE $tbl DROP CONSTRAINT c1")
        descDdL = sql(s"DESCRIBE EXTENDED $tbl").collect().map(_.mkString(","))
          .dropWhile(_ != "# Constraints,,")
        assert(descDdL === expectedConstraintsDdl
          .filter(_ != "c1,CHECK (c IS NOT NULL) ENFORCED NORELY,"))
      }
    }
  }

  test("describe table with column having only current default value") {
    withNamespaceAndTable("ns", "tbl") { tbl =>
      sql(s"CREATE TABLE $tbl (key int DEFAULT 13579) $defaultUsing " +
        "TBLPROPERTIES ('dropExistsDefault'=true)")
      checkAnswer(
        sql(s"DESCRIBE TABLE EXTENDED $tbl").where($"comment" === "13579"),
        Seq(Row("key", "int", "13579")))
    }
  }
}
