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

オープン 初心者向け
#398 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
1/5
見積もり時間
1〜3時間
初心者へのやさしさ
88/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
sql
領域
documentation

調査の方向性

issueで指定されたファイル SQL-Functions.md を更新します。ifnull() の項目を読み、構文と説明を OSQLFunctionIfNull について記載された動作と比較します。2つの呼び出し形式、三項演算的な動作の例、および最初の非NULL値を使うフォールバックチェーンについての coalesce() への相互参照を含めます。この項目が省略可能な第3引数と coalesce() との違いを正確に説明できていれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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).
主要言語
CSS
スター
59
フォーク
164
PR マージ指標
30日以内にマージされた PR はありません

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

orientechnologies/orientdb-docs のほかの issue

orientechnologies/orientdb-docs の issue をすべて見る

似ている issue

Documentation の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。