Kexi/Plugins/Queries/SQL Functions: Difference between revisions

From KDE Community Wiki
< Kexi‎ | Plugins‎ | Queries
No edit summary
 
(53 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page lists SQL functions that Kexi supports or wants to support. Aggregate functions are included. Support in particular SQL backends is compared (SQLite, PostgreSQL, MySQL). For practical reasons emphasis is put on concrete implementation instead of focusing on an SQL standard.
This page lists SQL functions that Kexi supports or wants to support. Aggregate functions are included. Support in particular SQL backends is compared (SQLite, PostgreSQL, MySQL). For practical reasons emphasis is put on concrete implementation instead of focusing on an SQL standard.
__TOC__
{{InProgress}}


==Functions==
Sections TODO:
*Logical Operators
*Comparison Operators
*Mathematical Functions and Operators
*String Functions and Operators
*Binary String Functions and Operators
*Bit String Functions and Operators
*Pattern Matching
*Data Type Formatting Functions
*Conditional Expressions
*Subquery Expressions
*Row and Array Comparisons
*System Information Functions
 
==Typical Scalar Functions==
These are typical scalar SQL functions returning a single value based on arguments.
 
TODO: taken from sqlite, split to categories
*SQLite docs: [https://www.sqlite.org/lang_corefunc.html Core Functions]
*SQLite docs: [https://www.sqlite.org/lang_corefunc.html Core Functions]
*PostgreSQL docs: [http://www.postgresql.org/docs/9.3/static/functions.html Functions and Operators]


{{KexiSQLFuncTableStart}}
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=abs(X)
{{KexiSQLFuncRow|name=abs(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=ceiling(X)
|desc=
|sqlite=DONE 2.9.8, using (CASE WHEN X = CAST(X AS INT) THEN CAST(X AS INT) WHEN X >= 0 THEN CAST(X AS INT) + 1 ELSE CAST(X AS INT) END)
|pg=DONE 2.9.8
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
Line 15: Line 43:
{{KexiSQLFuncRow|name=char(X1,X2,...,XN)
{{KexiSQLFuncRow|name=char(X1,X2,...,XN)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=
|my=
|my=
Line 23: Line 51:
{{KexiSQLFuncRow|name=coalesce(X,Y,...)
{{KexiSQLFuncRow|name=coalesce(X,Y,...)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8, using (CASE WHEN X = CAST(X AS INT) THEN CAST(X AS INT) WHEN X >= 0 THEN CAST(X AS INT) + 1 ELSE CAST(X AS INT) END)
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=floor(X)
|desc=
|sqlite=DONE 2.9.8, using (CASE WHEN X >= 0 OR X = CAST(X AS INT) THEN CAST(X AS INT) ELSE CAST(X AS INT) - 1 END)
|pg=DONE 2.9.8
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=greatest(X,Y,...) & alias max(X,Y,...)
|desc=
|sqlite=DONE 2.9.8 (adds COLLATE '')
|pg=DONE 2.9.8, uses (CASE WHEN (v0) IS NULL OR .. OR (vN) IS NULL THEN NULL ELSE GREATEST(v0,..,vN) END)
|my=DONE 2.9.8, see pgsql, TODO since 5.0.13 GREATEST() is enough
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=glob(X,Y)
{{KexiSQLFuncRow|name=hex(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8 using ENCODE(v, 'hex')
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
Line 39: Line 83:
{{KexiSQLFuncRow|name=ifnull(X,Y)
{{KexiSQLFuncRow|name=ifnull(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8, use coalesce()
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
Line 47: Line 91:
{{KexiSQLFuncRow|name=instr(X,Y)
{{KexiSQLFuncRow|name=instr(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=TODO use CREATE FUNCTION [http://www.postgresql.org/docs/9.0/static/plpgsql-porting.html]
|my=
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=least(X,Y,...) & alias min(X,Y,...)
|desc=
|sqlite=DONE 2.9.8 (adds COLLATE '')
|pg=DONE 2.9.8, uses (CASE WHEN (v0) IS NULL OR .. OR (vN) IS NULL THEN NULL ELSE GREATEST(v0,..,vN) END)
|my=DONE 2.9.8, see pgsql, TODO since 5.0.13 LEAST() is enough
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=length(X)
|desc=
|sqlite=DONE 2.9.8
|pg=DONE 2.9.8, for BLOBs octet_length() is used because length() for BLOB returns number of bits
|my=DONE 2.9.8, char_length() is used because length() in mysql returns number of bytes, what is not right for multibyte (unicode) encodings
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=lower(X)
|desc=
|sqlite=DONE 2.9.8
|pg=DONE 2.9.8
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=ltrim(X)
|desc=
|sqlite=DONE 2.9.8
|pg=DONE 2.9.8
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=hex(X)
{{KexiSQLFuncRow|name=ltrim(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=NOT supported, TODO
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=last_insert_rowid()
{{KexiSQLFuncRow|name=nullif(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=random()
|desc=Returns a random floating-point value v in the range 0 <= v < 1.0. NOTE: rand(X) which sets seed isn't portable between MySQL and PostgreSQL, and does not exist in SQLite, so we don't support it
|sqlite=DONE 2.9.8, uses (RANDOM() +9223372036854775807) /18446744073709551615)
|pg=DONE 2.9.8, uses random()
|my=DONE 2.9.8, uses rand()
|ms=
|xb=
}}
{{KexiSQLFuncRow|name=random(X,Y)
|desc=Returns returns a random integer that is equal or greater than X and less than Y
|sqlite=DONE 2.9.8, uses (X + CAST((Y - X) * (RANDOM() +9223372036854775807) /18446744073709551615 AS INT))
|pg=DONE 2.9.8, uses (X + FLOOR(RANDOM() * (Y - X))
|my=DONE 2.9.8, uses (X + FLOOR(RANDOM() * (Y - X))
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=length(X)
{{KexiSQLFuncRow|name=replace(X,Y,Z)
|desc=
|desc=
|sqlite=
|sqlite=
Line 77: Line 169:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=like(X,Y)
{{KexiSQLFuncRow|name=round(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=like(X,Y,Z)
{{KexiSQLFuncRow|name=round(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8 (support for Y<0 ignored)
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=lower(X)
{{KexiSQLFuncRow|name=rtrim(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=ltrim(X)
{{KexiSQLFuncRow|name=rtrim(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=NOT supported, TODO
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=ltrim(X,Y)
{{KexiSQLFuncRow|name=soundex(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8, "CREATE EXTENSION fuzzystrmatch" is called on connection
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=max(X,Y,...)
{{KexiSQLFuncRow|name=substr(X,Y,Z)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.1
|pg=
|pg=DONE 2.9.1
|my=
|my=DONE 2.9.1
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=min(X,Y,...)
{{KexiSQLFuncRow|name=substr(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.1
|pg=
|pg=DONE 2.9.1
|my=
|my=DONE 2.9.1
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=nullif(X,Y)
{{KexiSQLFuncRow|name=trim(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=printf(FORMAT,...)
{{KexiSQLFuncRow|name=trim(X,Y)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=NOT supported, TODO
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=quote(X)
{{KexiSQLFuncRow|name=unicode(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8, uses ASCII(X)
|my=
|my=DONE 2.9.8, ORD(CONVERT(X USING UTF16))
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=random()
{{KexiSQLFuncRow|name=upper(X)
|desc=
|desc=
|sqlite=
|sqlite=DONE 2.9.8
|pg=
|pg=DONE 2.9.8
|my=
|my=DONE 2.9.8
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=randomblob(N)
|}
 
==Date And Time Scalar Functions==
*SQLite docs: [https://www.sqlite.org/lang_datefunc.html Date And Time Functions]
*PostgreSQL docs: [http://www.postgresql.org/docs/9.3/static/functions-datetime.html Date/Time Functions and Operators]
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=date(timestring, modifier, modifier, ...)
|desc=
|desc=
|sqlite=
|sqlite=
Line 173: Line 272:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=replace(X,Y,Z)
{{KexiSQLFuncRow|name=time(timestring, modifier, modifier, ...)
|desc=
|desc=
|sqlite=
|sqlite=
Line 181: Line 280:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=round(X)
{{KexiSQLFuncRow|name=datetime(timestring, modifier, modifier, ...)
|desc=
|desc=
|sqlite=
|sqlite=
Line 189: Line 288:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=round(X,Y)
{{KexiSQLFuncRow|name=julianday(timestring, modifier, modifier, ...)
|desc=
|desc=
|sqlite=
|sqlite=
Line 197: Line 296:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=rtrim(X)
{{KexiSQLFuncRow|name=strftime(format, timestring, modifier, modifier, ...)
|desc=
|desc=
|sqlite=
|sqlite=
Line 205: Line 304:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=rtrim(X,Y)
|}
 
==Trigonometric Scalar Functions==
*SQLite has no such functions built-in but there's extension-functions.c at https://www.sqlite.org/contrib that we maybe can reuse. (check licese).
*PostgreSQL has them enabled, just test: https://www.postgresql.org/docs/9.6/static/functions-math.html#FUNCTIONS-MATH-TRIG-TABLE
*MySQL has them enabled: https://dev.mysql.com/doc/refman/5.7/en/mathematical-functions.html
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=....TODO
|desc=
|desc=
|sqlite=
|sqlite=
Line 213: Line 320:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=soundex(X)
|}
|desc=
 
==SQLite-specific Scalar Functions==
*SQLite docs: [https://www.sqlite.org/lang_corefunc.html Core Functions]
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=changes()
|desc=Returns the number of database rows that were changed or inserted or deleted by the most recently completed INSERT, DELETE, or UPDATE statement, exclusive of statements in lower-level triggers. The changes() SQL function is a wrapper around the [https://www.sqlite.org/c3ref/changes.html sqlite3_changes()] C/C++ function and hence follows the same rules for counting changes.
|sqlite=
|sqlite=
|pg=
|pg=
Line 221: Line 334:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=substr(X,Y,Z)
{{KexiSQLFuncRow|name=last_insert_rowid()
|desc=
|desc=Returns the ROWID of the last row insert from the database connection which invoked the function. The last_insert_rowid() SQL function is a wrapper around the sqlite3_last_insert_rowid() C/C++ interface function.
|sqlite=
|sqlite=
|pg=
|pg=
Line 229: Line 342:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=substr(X,Y)
{{KexiSQLFuncRow|name=glob(X,Y)
|desc=
|desc=The glob(X,Y) function is equivalent to the expression "Y GLOB X". Note that the X and Y arguments are reversed in the glob() function relative to the infix GLOB operator.
|sqlite=
|sqlite=DONE 2.9.7 but ifdef'd
|pg=
|pg=
|my=
|my=won't add; and even GLOB operator missing
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=trim(X)
{{KexiSQLFuncRow|name=like(X,Y), like(X,Y,Z)
|desc=
|desc=The like() function is used to implement the "Y LIKE X [ESCAPE Z]" expression. If the optional ESCAPE clause is present, then the like() function is invoked with three arguments. Otherwise, it is invoked with two arguments only. Note that the X and Y parameters are reversed in the like() function relative to the infix LIKE operator.
|sqlite=
|sqlite=DONE 2.9.7 but ifdef'd
|pg=
|pg=
|my=
|my=won't add: use LIKE operator instead
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=trim(X,Y)
{{KexiSQLFuncRow|name=likelihood(X,Y)
|desc=
|desc=Returns argument X unchanged. The value Y in likelihood(X,Y) must be a floating point constant between 0.0 and 1.0, inclusive. The likelihood(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles during run-time (that is, during calls to sqlite3_step()). The purpose of the likelihood(X,Y) function is to provide a hint to the query planner that the argument X is a boolean that is true with a probability of approximately Y. The unlikely(X) function is short-hand for likelihood(X,0.0625). The likely(X) function is short-hand for likelihood(X,0.9375).
|sqlite=
|sqlite=
|pg=
|pg=
Line 253: Line 366:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=typeof(X)
{{KexiSQLFuncRow|name=likely(X)
|desc=
|desc=Returns the argument X unchanged. The likely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the likely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually true. The likely(X) function is equivalent to likelihood(X,0.9375). See also: unlikely(X).
|sqlite=
|sqlite=
|pg=
|pg=
Line 261: Line 374:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=unicode(X)
{{KexiSQLFuncRow|name=load_extension(X)<br/>load_ extension(X,Y)
|desc=
|desc=Loads SQLite extensions out of the shared library file named X using the entry point Y. The result of [https://www.sqlite.org/loadext.html load_extension()] is always a NULL. If Y is omitted then the default entry point name is used. The load_extension() function raises an exception if the extension fails to load or initialize correctly.<br/>The load_extension() function will fail if the extension attempts to modify or delete an SQL function or collating sequence. The extension can add new functions or collating sequences, but cannot modify or delete existing functions or collating sequences because those functions and/or collating sequences might be used elsewhere in the currently running SQL statement. To load an extension that changes or deletes functions or collating sequences, use the [https://www.sqlite.org/c3ref/load_extension.html sqlite3_load_extension()] C-language API.<br/>For security reasons, extension loaded is turned off by default and must be enabled by a prior call to [https://www.sqlite.org/c3ref/enable_load_extension.html sqlite3_enable_load_extension()].
|sqlite=
|sqlite=
|pg=
|pg=
Line 269: Line 382:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=upper(X)
{{KexiSQLFuncRow|name=printf(FORMAT,...)
|desc=
|desc=Works like the sqlite3_mprintf() C-language function and the printf() function from the standard C library. The first argument is a format string that specifies how to construct the output string using values taken from subsequent arguments. If the FORMAT argument is missing or NULL then the result is NULL. The %n format is silently ignored and does not consume an argument. The %p format is an alias for %X. The %z format is interchangeable with %s. If there are too few arguments in the argument list, missing arguments are assumed to have a NULL value, which is translated into 0 or 0.0 for numeric formats or an empty string for %s.
|sqlite=
|sqlite=
|pg=
|pg=
Line 277: Line 390:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=zeroblob(N)
{{KexiSQLFuncRow|name=quote(X)
|desc=
|desc=Returns the text of an SQL literal which is the value of its argument suitable for inclusion into an SQL statement. Strings are surrounded by single-quotes with escapes on interior quotes as needed. BLOBs are encoded as hexadecimal literals. Strings with embedded NUL characters cannot be represented as string literals in SQL and hence the returned string literal is truncated prior to the first NUL.
|sqlite=
|sqlite=
|pg=
|pg=
Line 285: Line 398:
|xb=
|xb=
}}
}}
|}
{{KexiSQLFuncRow|name=randomblob(N)
 
|desc=Returns an N-byte blob containing pseudo-random bytes. If N is less than 1 then a 1-byte random blob is returned.<br/>Hint: applications can generate globally unique identifiers using this function together with hex() and/or lower() like this:<br/>hex(randomblob(16))<br/>lower(hex(randomblob(16)))
==Date And Time Functions==
*SQLite docs: [https://www.sqlite.org/lang_datefunc.html Date And Time Functions]
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=date(timestring, modifier, modifier, ...)
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 299: Line 406:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=time(timestring, modifier, modifier, ...)
{{KexiSQLFuncRow|name=sqlite_compileoption_get(N)
|desc=
|desc=A wrapper around the [https://www.sqlite.org/c3ref/compileoption_get.html sqlite3_compileoption_get()] C/C++ function. This routine returns the N-th compile-time option used to build SQLite or NULL if N is out of range. See also the [https://www.sqlite.org/pragma.html#pragma_compile_options compile_options] pragma.
|sqlite=
|sqlite=
|pg=
|pg=
Line 307: Line 414:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=datetime(timestring, modifier, modifier, ...)
{{KexiSQLFuncRow|name=sqlite_compileoption_used(X)
|desc=
|desc=A wrapper around the [https://www.sqlite.org/c3ref/compileoption_get.html sqlite3_compileoption_used()] C/C++ function. When the argument X to sqlite_compileoption_used(X) is a string which is the name of a compile-time option, this routine returns true (1) or false (0) depending on whether or not that option was used during the build.
|sqlite=
|sqlite=
|pg=
|pg=
Line 315: Line 422:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=julianday(timestring, modifier, modifier, ...)
{{KexiSQLFuncRow|name=sqlite_source_id()
|desc=
|desc=Returns a string that identifies the specific version of the source code that was used to build the SQLite library. The string returned by [https://www.sqlite.org/c3ref/libversion.html sqlite_source_id()] begins with the date and time that the source code was checked in and is follows by an SHA1 hash that uniquely identifies the source tree. This function is an SQL wrapper around the sqlite3_sourceid() C interface.
|sqlite=
|sqlite=
|pg=
|pg=
Line 323: Line 430:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=strftime(format, timestring, modifier, modifier, ...)
{{KexiSQLFuncRow|name=sqlite_version()
|desc=
|desc=Returns the version string for the SQLite library that is running. This function is an SQL wrapper around the [https://www.sqlite.org/c3ref/libversion.html sqlite3_libversion()] C-interface.
|sqlite=
|sqlite=
|pg=
|pg=
Line 331: Line 438:
|xb=
|xb=
}}
}}
|}
{{KexiSQLFuncRow|name=total_changes()
 
|desc=Returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the current database connection was opened. This function is a wrapper around the [https://www.sqlite.org/c3ref/total_changes.html sqlite3_total_changes()] C/C++ interface.
==Aggregate functions==
*SQLite docs: [https://www.sqlite.org/lang_aggfunc.html Aggregate Functions]
 
{{KexiSQLFuncTableStart}}
|}
 
==SQLite-specific Functions==
*SQLite docs: [https://www.sqlite.org/lang_corefunc.html Core Functions]
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=changes()
|desc=Returns the number of database rows that were changed or inserted or deleted by the most recently completed INSERT, DELETE, or UPDATE statement, exclusive of statements in lower-level triggers. The changes() SQL function is a wrapper around the [https://www.sqlite.org/c3ref/changes.html sqlite3_changes()] C/C++ function and hence follows the same rules for counting changes.  
|sqlite=
|sqlite=
|pg=
|pg=
Line 351: Line 446:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=likelihood(X,Y)
{{KexiSQLFuncRow|name=typeof(X)
|desc=Returns argument X unchanged. The value Y in likelihood(X,Y) must be a floating point constant between 0.0 and 1.0, inclusive. The likelihood(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles during run-time (that is, during calls to sqlite3_step()). The purpose of the likelihood(X,Y) function is to provide a hint to the query planner that the argument X is a boolean that is true with a probability of approximately Y. The unlikely(X) function is short-hand for likelihood(X,0.0625). The likely(X) function is short-hand for likelihood(X,0.9375).
|desc=
|sqlite=
|sqlite=
|pg=
|pg=maybe pg_typeof() but it's very different
|my=
|my=
|ms=
|ms=
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=likely(X)
{{KexiSQLFuncRow|name=unlikely(X)
|desc=Returns the argument X unchanged. The likely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the likely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually true. The likely(X) function is equivalent to likelihood(X,0.9375). See also: unlikely(X).  
|desc=Returns the argument X unchanged. The unlikely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the unlikely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually not true. The unlikely(X) function is equivalent to likelihood(X, 0.0625).  
|sqlite=
|sqlite=
|pg=
|pg=
Line 367: Line 462:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=load_extension(X)<br/>load_ extension(X,Y)
{{KexiSQLFuncRow|name=zeroblob(N)
|desc=Loads SQLite extensions out of the shared library file named X using the entry point Y. The result of [https://www.sqlite.org/loadext.html load_extension()] is always a NULL. If Y is omitted then the default entry point name is used. The load_extension() function raises an exception if the extension fails to load or initialize correctly.<br/>The load_extension() function will fail if the extension attempts to modify or delete an SQL function or collating sequence. The extension can add new functions or collating sequences, but cannot modify or delete existing functions or collating sequences because those functions and/or collating sequences might be used elsewhere in the currently running SQL statement. To load an extension that changes or deletes functions or collating sequences, use the [https://www.sqlite.org/c3ref/load_extension.html sqlite3_load_extension()] C-language API.<br/>For security reasons, extension loaded is turned off by default and must be enabled by a prior call to [https://www.sqlite.org/c3ref/enable_load_extension.html sqlite3_enable_load_extension()].
|desc=Returns a BLOB consisting of N bytes of 0x00. SQLite manages these zeroblobs very efficiently. Zeroblobs can be used to reserve space for a BLOB that is later written using incremental BLOB I/O. This SQL function is implemented using the sqlite3_result_zeroblob() routine from the C/C++ interface.  
|sqlite=
|sqlite=
|pg=
|pg=
Line 375: Line 470:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=sqlite_ compileoption_ get(N)
|}
|desc=A wrapper around the [https://www.sqlite.org/c3ref/compileoption_get.html sqlite3_compileoption_get()] C/C++ function. This routine returns the N-th compile-time option used to build SQLite or NULL if N is out of range. See also the [https://www.sqlite.org/pragma.html#pragma_compile_options compile_options] pragma.
 
==Aggregate functions==
*SQLite docs: [https://www.sqlite.org/lang_aggfunc.html Aggregate Functions]
*PostgreSQL docs: [http://www.postgresql.org/docs/9.3/static/functions-aggregate.html Aggregate Functions]
 
{{KexiSQLFuncTableStart}}
{{KexiSQLFuncRow|name=avg(X)
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 383: Line 485:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=sqlite_ compileoption_ used(X)
{{KexiSQLFuncRow|name=count(X)<br/>count(*)
|desc=A wrapper around the [https://www.sqlite.org/c3ref/compileoption_get.html sqlite3_compileoption_used()] C/C++ function. When the argument X to sqlite_compileoption_used(X) is a string which is the name of a compile-time option, this routine returns true (1) or false (0) depending on whether or not that option was used during the build.
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 391: Line 493:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=sqlite_ source_id()
{{KexiSQLFuncRow|name=group_concat(X)<br/>group_concat(X,Y)
|desc=Returns a string that identifies the specific version of the source code that was used to build the SQLite library. The string returned by [https://www.sqlite.org/c3ref/libversion.html sqlite_source_id()] begins with the date and time that the source code was checked in and is follows by an SHA1 hash that uniquely identifies the source tree. This function is an SQL wrapper around the sqlite3_sourceid() C interface.
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 399: Line 501:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=sqlite_version()
{{KexiSQLFuncRow|name=max(X)
|desc=Returns the version string for the SQLite library that is running. This function is an SQL wrapper around the [https://www.sqlite.org/c3ref/libversion.html sqlite3_libversion()] C-interface.
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 407: Line 509:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=total_changes()
{{KexiSQLFuncRow|name=min(X)
|desc=Returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the current database connection was opened. This function is a wrapper around the [https://www.sqlite.org/c3ref/total_changes.html sqlite3_total_changes()] C/C++ interface.
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 415: Line 517:
|xb=
|xb=
}}
}}
{{KexiSQLFuncRow|name=unlikely(X)
{{KexiSQLFuncRow|name=sum(X)<br/>total(X)
|desc=Returns the argument X unchanged. The unlikely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the unlikely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually not true. The unlikely(X) function is equivalent to likelihood(X, 0.0625).
|desc=
|sqlite=
|sqlite=
|pg=
|pg=
Line 424: Line 526:
}}
}}
|}
|}


==Further work==
==Further work==
Add comparison for other backends: Sybase/MSSQL, xBase.
*Model sections after pgsql, which probably has one of the larger feature set: [http://www.postgresql.org/docs/9.5/static/functions.html]
*Add comparison for other backends: Sybase/MSSQL, xBase.
*Functions missing in SQLite that can be added via the extension API: [https://www.devart.com/dotconnect/sqlite/docs/UDF_implemented.html], [https://www.sqlite.org/contrib extension-functions.c]


==Links==
==Links==
*[https://en.wikipedia.org/wiki/SQL SQL] (Wikipedia)
*SQL Tutorial: www.tutorialspoint.com/sql/index.htm
*[http://dev.mysql.com/doc/refman/5.0/en/compatibility.html MySQL Standards Compliance]
*[http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt sql-92 standard]
*[https://wiki.postgresql.org/wiki/Things_to_find_out_about_when_moving_from_MySQL_to_PostgreSQL Things to find out about when moving from MySQL to PostgreSQL]
*[http://troels.arvin.dk/db/rdbms Comparison of different SQL implementations]

Latest revision as of 17:09, 27 March 2017

This page lists SQL functions that Kexi supports or wants to support. Aggregate functions are included. Support in particular SQL backends is compared (SQLite, PostgreSQL, MySQL). For practical reasons emphasis is put on concrete implementation instead of focusing on an SQL standard.

Note

This is work in progress. You can contribute to this page or request updates.


Sections TODO:

  • Logical Operators
  • Comparison Operators
  • Mathematical Functions and Operators
  • String Functions and Operators
  • Binary String Functions and Operators
  • Bit String Functions and Operators
  • Pattern Matching
  • Data Type Formatting Functions
  • Conditional Expressions
  • Subquery Expressions
  • Row and Array Comparisons
  • System Information Functions

Typical Scalar Functions

These are typical scalar SQL functions returning a single value based on arguments.

TODO: taken from sqlite, split to categories


Name Description sqlite pgsql mysql mssql xbase
abs(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
ceiling(X) DONE 2.9.8, using (CASE WHEN X = CAST(X AS INT) THEN CAST(X AS INT) WHEN X >= 0 THEN CAST(X AS INT) + 1 ELSE CAST(X AS INT) END) DONE 2.9.8 DONE 2.9.8
char(X1,X2,...,XN) DONE 2.9.8
coalesce(X,Y,...) DONE 2.9.8, using (CASE WHEN X = CAST(X AS INT) THEN CAST(X AS INT) WHEN X >= 0 THEN CAST(X AS INT) + 1 ELSE CAST(X AS INT) END) DONE 2.9.8 DONE 2.9.8
floor(X) DONE 2.9.8, using (CASE WHEN X >= 0 OR X = CAST(X AS INT) THEN CAST(X AS INT) ELSE CAST(X AS INT) - 1 END) DONE 2.9.8 DONE 2.9.8
greatest(X,Y,...) & alias max(X,Y,...) DONE 2.9.8 (adds COLLATE ) DONE 2.9.8, uses (CASE WHEN (v0) IS NULL OR .. OR (vN) IS NULL THEN NULL ELSE GREATEST(v0,..,vN) END) DONE 2.9.8, see pgsql, TODO since 5.0.13 GREATEST() is enough
hex(X) DONE 2.9.8 DONE 2.9.8 using ENCODE(v, 'hex') DONE 2.9.8
ifnull(X,Y) DONE 2.9.8 DONE 2.9.8, use coalesce() DONE 2.9.8
instr(X,Y) DONE 2.9.8 TODO use CREATE FUNCTION [1] DONE 2.9.8
least(X,Y,...) & alias min(X,Y,...) DONE 2.9.8 (adds COLLATE ) DONE 2.9.8, uses (CASE WHEN (v0) IS NULL OR .. OR (vN) IS NULL THEN NULL ELSE GREATEST(v0,..,vN) END) DONE 2.9.8, see pgsql, TODO since 5.0.13 LEAST() is enough
length(X) DONE 2.9.8 DONE 2.9.8, for BLOBs octet_length() is used because length() for BLOB returns number of bits DONE 2.9.8, char_length() is used because length() in mysql returns number of bytes, what is not right for multibyte (unicode) encodings
lower(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
ltrim(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
ltrim(X,Y) DONE 2.9.8 DONE 2.9.8 NOT supported, TODO
nullif(X,Y) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
random() Returns a random floating-point value v in the range 0 <= v < 1.0. NOTE: rand(X) which sets seed isn't portable between MySQL and PostgreSQL, and does not exist in SQLite, so we don't support it DONE 2.9.8, uses (RANDOM() +9223372036854775807) /18446744073709551615) DONE 2.9.8, uses random() DONE 2.9.8, uses rand()
random(X,Y) Returns returns a random integer that is equal or greater than X and less than Y DONE 2.9.8, uses (X + CAST((Y - X) * (RANDOM() +9223372036854775807) /18446744073709551615 AS INT)) DONE 2.9.8, uses (X + FLOOR(RANDOM() * (Y - X)) DONE 2.9.8, uses (X + FLOOR(RANDOM() * (Y - X))
replace(X,Y,Z)
round(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
round(X,Y) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8 (support for Y<0 ignored)
rtrim(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
rtrim(X,Y) DONE 2.9.8 DONE 2.9.8 NOT supported, TODO
soundex(X) DONE 2.9.8 DONE 2.9.8, "CREATE EXTENSION fuzzystrmatch" is called on connection DONE 2.9.8
substr(X,Y,Z) DONE 2.9.1 DONE 2.9.1 DONE 2.9.1
substr(X,Y) DONE 2.9.1 DONE 2.9.1 DONE 2.9.1
trim(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8
trim(X,Y) DONE 2.9.8 DONE 2.9.8 NOT supported, TODO
unicode(X) DONE 2.9.8 DONE 2.9.8, uses ASCII(X) DONE 2.9.8, ORD(CONVERT(X USING UTF16))
upper(X) DONE 2.9.8 DONE 2.9.8 DONE 2.9.8

Date And Time Scalar Functions


Name Description sqlite pgsql mysql mssql xbase
date(timestring, modifier, modifier, ...)
time(timestring, modifier, modifier, ...)
datetime(timestring, modifier, modifier, ...)
julianday(timestring, modifier, modifier, ...)
strftime(format, timestring, modifier, modifier, ...)

Trigonometric Scalar Functions


Name Description sqlite pgsql mysql mssql xbase
....TODO

SQLite-specific Scalar Functions


Name Description sqlite pgsql mysql mssql xbase
changes() Returns the number of database rows that were changed or inserted or deleted by the most recently completed INSERT, DELETE, or UPDATE statement, exclusive of statements in lower-level triggers. The changes() SQL function is a wrapper around the sqlite3_changes() C/C++ function and hence follows the same rules for counting changes.
last_insert_rowid() Returns the ROWID of the last row insert from the database connection which invoked the function. The last_insert_rowid() SQL function is a wrapper around the sqlite3_last_insert_rowid() C/C++ interface function.
glob(X,Y) The glob(X,Y) function is equivalent to the expression "Y GLOB X". Note that the X and Y arguments are reversed in the glob() function relative to the infix GLOB operator. DONE 2.9.7 but ifdef'd won't add; and even GLOB operator missing
like(X,Y), like(X,Y,Z) The like() function is used to implement the "Y LIKE X [ESCAPE Z]" expression. If the optional ESCAPE clause is present, then the like() function is invoked with three arguments. Otherwise, it is invoked with two arguments only. Note that the X and Y parameters are reversed in the like() function relative to the infix LIKE operator. DONE 2.9.7 but ifdef'd won't add: use LIKE operator instead
likelihood(X,Y) Returns argument X unchanged. The value Y in likelihood(X,Y) must be a floating point constant between 0.0 and 1.0, inclusive. The likelihood(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles during run-time (that is, during calls to sqlite3_step()). The purpose of the likelihood(X,Y) function is to provide a hint to the query planner that the argument X is a boolean that is true with a probability of approximately Y. The unlikely(X) function is short-hand for likelihood(X,0.0625). The likely(X) function is short-hand for likelihood(X,0.9375).
likely(X) Returns the argument X unchanged. The likely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the likely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually true. The likely(X) function is equivalent to likelihood(X,0.9375). See also: unlikely(X).
load_extension(X)
load_ extension(X,Y)
Loads SQLite extensions out of the shared library file named X using the entry point Y. The result of load_extension() is always a NULL. If Y is omitted then the default entry point name is used. The load_extension() function raises an exception if the extension fails to load or initialize correctly.
The load_extension() function will fail if the extension attempts to modify or delete an SQL function or collating sequence. The extension can add new functions or collating sequences, but cannot modify or delete existing functions or collating sequences because those functions and/or collating sequences might be used elsewhere in the currently running SQL statement. To load an extension that changes or deletes functions or collating sequences, use the sqlite3_load_extension() C-language API.
For security reasons, extension loaded is turned off by default and must be enabled by a prior call to sqlite3_enable_load_extension().
printf(FORMAT,...) Works like the sqlite3_mprintf() C-language function and the printf() function from the standard C library. The first argument is a format string that specifies how to construct the output string using values taken from subsequent arguments. If the FORMAT argument is missing or NULL then the result is NULL. The %n format is silently ignored and does not consume an argument. The %p format is an alias for %X. The %z format is interchangeable with %s. If there are too few arguments in the argument list, missing arguments are assumed to have a NULL value, which is translated into 0 or 0.0 for numeric formats or an empty string for %s.
quote(X) Returns the text of an SQL literal which is the value of its argument suitable for inclusion into an SQL statement. Strings are surrounded by single-quotes with escapes on interior quotes as needed. BLOBs are encoded as hexadecimal literals. Strings with embedded NUL characters cannot be represented as string literals in SQL and hence the returned string literal is truncated prior to the first NUL.
randomblob(N) Returns an N-byte blob containing pseudo-random bytes. If N is less than 1 then a 1-byte random blob is returned.
Hint: applications can generate globally unique identifiers using this function together with hex() and/or lower() like this:
hex(randomblob(16))
lower(hex(randomblob(16)))
sqlite_compileoption_get(N) A wrapper around the sqlite3_compileoption_get() C/C++ function. This routine returns the N-th compile-time option used to build SQLite or NULL if N is out of range. See also the compile_options pragma.
sqlite_compileoption_used(X) A wrapper around the sqlite3_compileoption_used() C/C++ function. When the argument X to sqlite_compileoption_used(X) is a string which is the name of a compile-time option, this routine returns true (1) or false (0) depending on whether or not that option was used during the build.
sqlite_source_id() Returns a string that identifies the specific version of the source code that was used to build the SQLite library. The string returned by sqlite_source_id() begins with the date and time that the source code was checked in and is follows by an SHA1 hash that uniquely identifies the source tree. This function is an SQL wrapper around the sqlite3_sourceid() C interface.
sqlite_version() Returns the version string for the SQLite library that is running. This function is an SQL wrapper around the sqlite3_libversion() C-interface.
total_changes() Returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the current database connection was opened. This function is a wrapper around the sqlite3_total_changes() C/C++ interface.
typeof(X) maybe pg_typeof() but it's very different
unlikely(X) Returns the argument X unchanged. The unlikely(X) function is a no-op that the code generator optimizes away so that it consumes no CPU cycles at run-time (that is, during calls to sqlite3_step()). The purpose of the unlikely(X) function is to provide a hint to the query planner that the argument X is a boolean value that is usually not true. The unlikely(X) function is equivalent to likelihood(X, 0.0625).
zeroblob(N) Returns a BLOB consisting of N bytes of 0x00. SQLite manages these zeroblobs very efficiently. Zeroblobs can be used to reserve space for a BLOB that is later written using incremental BLOB I/O. This SQL function is implemented using the sqlite3_result_zeroblob() routine from the C/C++ interface.

Aggregate functions


Name Description sqlite pgsql mysql mssql xbase
avg(X)
count(X)
count(*)
group_concat(X)
group_concat(X,Y)
max(X)
min(X)
sum(X)
total(X)


Further work

  • Model sections after pgsql, which probably has one of the larger feature set: [2]
  • Add comparison for other backends: Sybase/MSSQL, xBase.
  • Functions missing in SQLite that can be added via the extension API: [3], extension-functions.c

Links