Control de errores en Azure Databricks

Se aplica a: Databricks SQL Databricks Runtime 12.2 y versiones posteriores

Componentes de error

Cuando Azure Databricks genera un error, incluye los siguientes componentes:

• Condición de error

  Cadena descriptiva, legible y legible, única para la condición de error.

  Algunas condiciones de error incluyen subcondiciones.

  Por ejemplo: TABLE_OR_VIEW_NOT_FOUND y INCOMPLETE_TYPE_DEFINITION. MATRIZ.

  Para obtener una lista de todas las condiciones de error, consulte Condiciones de error.

• SQLSTATE

  Cadena larga de cinco caracteres, agrupando las condiciones de error en un formato estándar admitido por muchos productos y API.

  Por ejemplo: '42P01'

  Para obtener una lista completa de todos los SQLSTATEusados por Azure Databricks, vea SQLSTATEs.

• Mensajes con parámetros

  Mensaje de error con marcadores de posición para los parámetros.

  Por ejemplo: TABLE_OR_VIEW_NOT_FOUND incluye el siguiente mensaje:

  The table or view <relationName> cannot be found.
  

  Puede usar el mensaje con parámetros para representar un mensaje de error asignando valores de parámetro de mensaje a las etiquetas de parámetro <parameter>.

• Parámetros de mensaje

  Mapa de parámetros y valores que proporcionan información adicional sobre el error. Por ejemplo: 'relationName' -> 'main.default.tab1'.

• Mensaje

  El mensaje de error mostrado completamente, incluida la condición de error y el SQLSTATE, con los parámetros rellenados. Por ejemplo:

  [TABLE_OR_VIEW_NOT_FOUND] The table or view `does_not_exist` cannot be found. Verify the spelling and correctness of the schema and catalog.
  If you did not qualify the name with a schema, verify the current_schema() output, or qualify the name with the correct schema and catalog.
  To tolerate the error on drop use DROP VIEW IF EXISTS or DROP TABLE IF EXISTS. SQLSTATE: 42P01; line 1 pos 14;
  'Project [*]
  +- 'UnresolvedRelation [does_not_exist], [], false
  

Advertencia

Mensaje y Parámetro de mensaje no son estables entre versiones. El texto del mensaje se puede cambiar o localizar sin previo aviso. Para manejar programáticamente una condición de error, use Error Condition, SQLSTATE, y Parámetros del Mensaje en su lugar.

Control de condiciones de error

Se aplica a: Databricks SQL Databricks Runtime 14.2 y superior

Importante

Esta característica está en versión preliminar pública.

Azure Databricks proporciona API específicas del lenguaje para controlar las condiciones de error.

SQL

Se aplica a: Databricks SQL Databricks Runtime 16.3 y versiones posteriores

Para SQL, use la sintaxis de instrucción compuesta para definir controladores de condición.

• DECLARE EXIT HANDLER: define un controlador para un conjunto de condiciones de error, SQLSTATE o cualquier SQLEXCEPTION.
• GET DIAGNÓSTICOS: recupera los parámetros de la condición de error, SQLSTATE, y el mensaje de la condición de error interceptada por el controlador.

Pitón

Para Python, use pySparkException

• PySparkException.getErrorClass(): devuelve la condición de error de la excepción como una cadena.
• PySparkException.getMessageParameters(): Devuelve los parámetros de mensaje de la excepción como diccionario.
• PySparkException.getSqlState(): Devuelve el SQLSTATE de la expresión como una cadena.

Scala

Para Scala, use SparkThrowable

• getErrorClass(): devuelve una condición de error como una cadena.
• getMessageParameters(): Devuelve un parámetro de mensaje como un mapa.
• getSqlState(): devuelve un SQLSTATE como una cadena.

Ejemplos

• Capture cualquier excepción y muestre la condición de error, los parámetros de mensaje y SQLSTATE. Mostrar también el mensaje de error predeterminado

  SQL

  BEGIN
    DECLARE EXIT HANDLER FOR SQLEXCEPTION
      BEGIN
        DECLARE error_condition STRING;
        DECLARE sqlstate STRING;
        DECLARE msg_args MAP<STRING, STRING>;
        DECLARE msg STRING;
  
        GET DIAGNOSTICS CONDITION 1
          error_condition = CONDITION_IDENTIFIER,
          sqlstate        = RETURNED_SQLSTATE,
          msg_args        = MESSAGE_ARGUMENTS,
          msg             = MESSAGE_TEXT;
  
        VALUES('Error Condition   : ' || error_condition         ),
              ('Message arguments : ' || cast(msg_args AS STRING)),
              ('SQLSTATE          : ' || sqlstate                ),
              (msg                                               );
      END;
    SELECT * FROM does_not_exist;
  END;
  

  Scala

  import org.apache.spark.SparkThrowable
  
  try {
    spark.sql("SELECT * FROM does_not_exist").show()
  }
  catch {
    case ex: SparkThrowable =>
      println("Error Condition   : " + ex.getErrorClass)
      println("Message arguments : " + ex.getMessageParameters())
      println("SQLSTATE          : " + ex.getSqlState)
      println(ex)
  }
  

  Pitón

  from pyspark.errors import PySparkException
  
  try:
    spark.sql("SELECT * FROM does_not_exist").show()
  except PySparkException as ex:
    print("Error Condition   : " + ex.getErrorClass())
    print("Message arguments : " + str(ex.getMessageParameters()))
    print("SQLSTATE          : " + ex.getSqlState())
    print(ex)
  

  Resultado

    Error Condition   : TABLE_OR_VIEW_NOT_FOUND
    Message arguments : {'relationName': '`does_not_exist`'}
    SQLSTATE          : 42P01
    [TABLE_OR_VIEW_NOT_FOUND] The table or view `does_not_exist` cannot be found. Verify the spelling and correctness of the schema and catalog.
    If you did not qualify the name with a schema, verify the current_schema() output, or qualify the name with the correct schema and catalog.
    To tolerate the error on drop use DROP VIEW IF EXISTS or DROP TABLE IF EXISTS. SQLSTATE: 42P01; line 1 pos 14;
    'Project [*]
    +- 'UnresolvedRelation [does_not_exist], [], false
  

• Capture solo el SQLSTATE 42P01 y muestre un mensaje personalizado:

  SQL

  BEGIN
    DECLARE EXIT HANDLER FOR SQLSTATE '42P01'
      BEGIN
        DECLARE msg_args MAP<STRING, STRING>;
        GET DIAGNOSTICS CONDITION 1 msg_args = MESSAGE_ARGUMENTS;
        VALUES('I\'m so sorry, but I cannot find: ' || msg_args['relationName']);
      END;
    SELECT * FROM does_not_exist;
  END;
  

  Scala

  import org.apache.spark.SparkThrowable
  
  try {
    spark.sql("SELECT * FROM does_not_exist").show()
  }
  catch {
    case ex: SparkThrowable if (ex.getSqlState == "42P01") =>
      println("I'm so sorry, but I cannot find: " + ex.getMessageParameters().get("relationName"))
  }
  

  Pitón

  from pyspark.errors import PySparkException
  
  try:
    spark.sql("SELECT * FROM does_not_exist").show()
  except PySparkException as ex:
    if (ex.getSqlState() == "42P01"):
      print("I'm so sorry, but I cannot find: " + ex.getMessageParameters()['relationName'])
    else:
      raise
  

  Resultado

  I'm so sorry, but I cannot find: `does_not_exist`
  

• Capture solo la condición TABLE_OR_VIEW_NOT_FOUND de error y muestre un mensaje personalizado:

  SQL

  BEGIN
    DECLARE EXIT HANDLER FOR TABLE_OR_VIEW_NOT_FOUND
      BEGIN
        DECLARE msg_args MAP<STRING, STRING>;
        GET DIAGNOSTICS CONDITION 1 msg_args = MESSAGE_ARGUMENTS;
        VALUES('I\'m so sorry, but I cannot find: ' || msg_args['relationName']);
      END;
    SELECT * FROM does_not_exist;
  END;
  

  Scala

  import org.apache.spark.SparkThrowable
  
  try {
    spark.sql("SELECT * FROM does_not_exist").show()
  }
  catch {
    case ex: SparkThrowable if (ex.getErrorClass == "TABLE_OR_VIEW_NOT_FOUND") =>
      println("I'm so sorry, but I cannot find: " + ex.getMessageParameters().get("relationName"))
  }
  

  Pitón

  from pyspark.errors import PySparkException
  
  try:
    spark.sql("SELECT * FROM does_not_exist").show()
  except PySparkException as ex:
    if (ex.getErrorClass() == "TABLE_OR_VIEW_NOT_FOUND"):
      print("I'm so sorry, but I cannot find: " + ex.getMessageParameters()['relationName'])
    else:
      raise
  

  Resultado

  I'm so sorry, but I cannot find: `does_not_exist`
  

Excepciones generadas por el usuario

Azure Databricks proporciona las siguientes funciones para generar errores definidos por el usuario:

• raise_error

  Genera una excepción con un mensaje de error personalizado.

• assert_true

  Genera un error con un mensaje de error opcional, si no se cumple una condición.

Ambas funciones devuelven la condición de error "USER_RAISED_EXCEPTION" junto con un mensaje definido por el usuario SQLSTATE'P0001'.

Ejemplos

> SELECT raise_error('This is a custom error message');
 [USER_RAISED_EXCEPTION] This is a custom error message. SQLSTATE: P0001

> SELECT assert_true(1 = 2, 'One is not two!');
 [USER_RAISED_EXCEPTION] One is not two! SQLSTATE: P0001

> SELECT assert_true(1 = 2);
 [USER_RAISED_EXCEPTION] '(1 = 2)' is not true! SQLSTATE: P0001

Temas relacionados

• assert_true Función
• raise_error Función
• Instrucción compuesta BEGIN END
• GET Instrucción DIAGNOSTICS