Skip to content

Add documentation for <=> operator #14203

Closed

Description

@comphead

It would also be nice to add a section to the doc about this operator: https://datafusion.apache.org/user-guide/sql/operators.html#comparison-operators

However, we can do the docs as a follow on PR as well

Originally posted by @alamb in #14187 (review)

Activity

  1. Spaarsh commented on Jan 19, 2025

    @Spaarsh
    Contributor

    take

  2. alamb commented on Jan 20, 2025

    @alamb
    Contributor

    Thanks @comphead and @Spaarsh !

  3. Spaarsh commented on Jan 20, 2025

    @Spaarsh
    Contributor

    This is what I have added to the documentation. For all the existing operators, single examples sufficed since they followed a "one-way" comparison. While the spaceship operator is a three-way comparation. If this seems excessive, please let me know!


    (op_spaceship)=

    <=>

    Three-way comparision operator. A NULL-safe operator that returns true if both operands are equal or both are NULL, false otherwise.

    > SELECT NULL <=> NULL;
    +--------------------------------+
    | NULL IS NOT DISTINCT FROM NULL |
    +--------------------------------+
    | true                           |
    +--------------------------------+
    > SELECT 1 <=> NULL;
    +------------------------------------+
    | Int64(1) IS NOT DISTINCT FROM NULL |
    +------------------------------------+
    | false                              |
    +------------------------------------+
    > SELECT 1 <=> 2;
    +----------------------------------------+
    | Int64(1) IS NOT DISTINCT FROM Int64(2) |
    +----------------------------------------+
    | false                                  |
    +----------------------------------------+
    > SELECT 1 <=> 1;
    +----------------------------------------+
    | Int64(1) IS NOT DISTINCT FROM Int64(1) |
    +----------------------------------------+
    | true                                   |
    +----------------------------------------+

    I would also like to suggest that for the sake of clarity, we ensure that the description of the Spaceship operator is the similar to that of IS DISTINCT FROM. The documentation for IS DISTINCT FROM`` says this in the description: Guarantees the result of a comparison is true or false and not an empty set```

    So the description for the Spaceship Operator becomes:
    Three-way comparison operator. Guarantees the result of a comparison is `true` or `false` and not an empty set.

    But I feel this explanation to be lacking. Hence my suggestion is to change the description of IS DISTINCT FROM`` to the one I have chosen for the Spaceship operator. Hence, the description for IS DISTINCT FROMwould become:A NULL-safe operator that returns false if both operands are equal or both are NULL, true otherwise.```

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions