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

Aperta Adatta ai principianti
#398 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
1/5
Tempo stimato
1-3 ore
Idoneità per principianti
88/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
sql
Ambito
documentation

Direzione di ricerca

Aggiorna SQL-Functions.md, il file indicato nell’issue. Leggi la voce relativa a ifnull() e confronta la sintassi e la descrizione con il comportamento descritto per OSQLFunctionIfNull; includi entrambe le forme di chiamata, esempi del comportamento ternario e un rimando a coalesce() per le catene di fallback che usano il primo valore non nullo. Il lavoro è concluso quando la voce documenta correttamente il terzo argomento facoltativo e la differenza rispetto a coalesce().

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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).
Lingua principale
CSS
Stelle
59
Fork
164
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di orientechnologies/orientdb-docs

Tutte le issue di orientechnologies/orientdb-docs

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.