Documentation mismatch and confusing syntax for `ifnull()` 3-argument variant

Abierto Apto para principiantes
#398 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
88/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
sql

Línea de trabajo

Actualiza SQL-Functions.md, el archivo mencionado en la incidencia. Lee la entrada de ifnull() y compara la sintaxis y la descripción con el comportamiento descrito para OSQLFunctionIfNull; incluye ambas formas de invocación, ejemplos del comportamiento ternario y una referencia cruzada a coalesce() para cadenas de respaldo que usan el primer valor no nulo. El trabajo estará terminado cuando la entrada documente correctamente el tercer argumento opcional y la diferencia con coalesce().

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

OrientDB Version: 1.3.0 through 3.2.x / develop
Component: SQL Functions / Documentation (SQL-Functions.md)

Description

The SQL function ifnull() supports both 2 and 3 arguments in code (OSQLFunctionIfNull), but the official documentation in SQL-Functions.md is incomplete, has malformed grammar, and omits the 3rd argument from the syntax definition and examples.

Furthermore, because standard SQL / MySQL / SQLite IFNULL() strictly takes 2 arguments, users and reviewers who encounter 3 arguments often mistakenly assume either:

  1. OrientDB ifnull() only takes 2 arguments, or
  2. The 3-argument version behaves like coalesce() (returning the first non-null argument).

In reality, OrientDB's 3-argument ifnull() behaves like Oracle's NVL2() (ternary condition: val != null ? arg3 : arg2).


Documentation Issues in SQL-Functions.md

  1. Syntax definition omits the 3rd argument:
    The code defines super(NAME, 2, 3) with syntax ifnull(<field|value>, <return_value_if_null> [,<return_value_if_not_null>]), but the documentation only shows ifnull(<field/value>, <return_value_if_null>).
  2. Broken sentence in description:
    "Returns the passed field/value (or optional parameter *return_value_if_not_null*). If field/value is not null, otherwise it returns *return_value_if_null*."
    The original JavaDoc in OSQLFunctionIfNull.java reads:

    "Returns the passed field/value (or optional parameter return_value_if_not_null) if field/value is not null; otherwise it returns return_value_if_null."

  3. No 3-argument example:
    There are no examples demonstrating the 3-argument ternary behavior or clarifying that for first-non-null fallbacks (coalesce), coalesce() should be used instead.

Actual Code Behavior (OSQLFunctionIfNull.java)

public OSQLFunctionIfNull() {
  super(NAME, 2, 3);
}

@Override
public Object execute(...) {
  if (iParams[0] != null) {
    if (iParams.length == 3) {
      return iParams[2];
    }
    return iParams[0];
  }
  return iParams[1];
}
  • ifnull('a', 'b') -> 'a'
  • ifnull('a', 'b', 'c') -> 'c'
  • ifnull(null, 'b') -> 'b'
  • ifnull(null, 'b', 'c') -> 'b'
  • ifnull(null, null, 'x') -> null (not 'x')

Expected Documentation

Update SQL-Functions.md to:

  1. Correct the syntax to show the optional 3rd argument:
    ifnull(<field|value>, <return_value_if_null> [, <return_value_if_not_null>])
    
  2. Fix the description phrasing and clarify the ternary semantics:

    Returns the passed field|value (or optional parameter return_value_if_not_null) if field|value is not null; otherwise returns return_value_if_null.

  3. Add examples for both 2-argument and 3-argument invocations.
  4. Add a note/cross-reference pointing users to coalesce() if they need a multi-argument fallback chain (first non-null value).
Lenguaje dominante
CSS
Estrellas
59
Forks
164
Métricas de merge de PR
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de orientechnologies/orientdb-docs

Todos los issues de orientechnologies/orientdb-docs

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.