Softerra LDAP Administrator HelpShow AllHide All

LDAP-SQL Syntax Basics

LDAP-SQL is an SQL dialect that allows searching, adding, modifying, and deleting data in LDAP directories using SQL-like syntax expressions.

There are four basic statements that make the basis of the LDAP-SQL dialect:

The LDAP-SQL language is constructed from letters, digits, symbols, and whitespace, as defined in the following table.

TypeCharacters
Letters A-Z,a-z
Digits 0-9
Symbols ~!@#$%*()_-+=|[ ]{ }:;"'< >?/
Whitespace space, tab, carriage return

LDAP-SQL keywords are not case-sensitive, so lower-case letters are equivalent to corresponding upper-case letters except within string and character literals.

Characters are grouped together into the lexical units: delimiters, string and numeric constants, attribute names, data types, different operators, functions and comments.

LDAP-SQL Statement Delimiter

Semicolon is the standard way to separate each SQL statement.

SELECT * FROM ROOTDSE;
UPDATE "cn=TestContainer,DC=company" SET $description="my description"
WHERE $objectClass="user";

However, only one statement can be executed at a time.

String Constants

A string constant is an arbitrary sequence of characters enclosed in single (') or double (") quotation marks, e.g. 'this is a string'. In order to use a quote in such a string, use two quotation marks in succession, e.g. 'Jhon''s car'. Also, you can use a backslash to escape a single quote character in a string, e.g. 'Jhon\'s car'. All mentioned above, also applies to strings enclosed in double quotation marks, but in this case the double quotation mark is escaped with the help of two double quotation marks ("") or a backslash (\"). For example, the string There's a "test" string can be represented in the following ways:

            'There''s a "test" string' or 'There\'s a "test" string'

or

           "There's a ""test"" string" or "There's a \"test\" string"

Two string constants that are only separated by a whitespace with at least one newline are concatenated and handled as if the string had been written as one constant. For example:

            SELECT * FROM 'dc='
               'company';

is equivalent to

            SELECT * FROM 'dc=company';

but

            SELECT * FROM 'dc='     'company';

is not valid syntax.

LDAP-SQL also accepts escape string constants, which are an extension to the SQL standard. Within an escape string, a backslash character (\) begins a C-like backslash escape sequence, in which the combination of backslash and following character(s) represents a special byte value.

Backslash Escape SequenceInterpretation
\b backspace
\f from feed
\n new line
\r carriage return
\t tab
\\ backslash

String constants can have the @ prefix that prevents the escaping of symbol constants. Below is an example of a string with escaped characters

            "C:\\Test\\Example"

The same string without escaping

            @"C:\Test\Example"

Numeric Constants

Numeric constants are allowed in the following format:

[-]digits

where digits is one or more decimal digits (0 through 9). There may not be any spaces or other characters embedded in the constant. These are some examples of valid numeric constants:

            42
            -1232
            34234324324

LDAP Attributes Names

LDAP attribute names are specified in SQL code using the $ prefix

            SELECT $cn, $description, $objectClass FROM "DC=company,DC=com"

If an LDAP attribute name contains not only letters and digits, but also some other symbols, then this attribute name should be enclosed in double quotation marks.

            SELECT $"ms-DS-CreatorSID" FROM "DC=company,DC=com"
            WHERE $objectClass="user"

When using IntelliSense, attribute names are automatically inserted with the $ prefix and, if needed, are enclosed in double quotation marks.

Data Types

In LDAP-SQL, each LDAP attribute, expression, function input parameter, etc. has a corresponding data type. Data type identifies the type of data that object can hold: integer data, string data, date and time and so on. The following data types are defined in LDAP-SQL:

Data TypeDescription
Boolean Logical data type. Can be TRUE or FALSE.
Integer Signed integer values that range from -2147483648 through 2147483647.
LongInteger Signed integer values that range from -9223372036854775808 through 9223372036854775807.
String Symbol string of any length.
UTC The UTC data type represents date and time values in the format YYMMDDHHMMSS.0Z, where

YY - last two digits of the year
MM - two-digit month (01=January, etc.)
DD - two-digit day of month (01 through 31)
hh - two digits of hour (00 through 23) (am/pm NOT allowed)
mm - two digits of minute (00 through 59)
ss - two digits of second (00 through 59)

In this way, date 1997-07-16 19:20:30 in the UTC format will look as follows:
970716192030.0Z
GeneralizedTime The GeneralizedTime date type represents date and time values in the format YYYYMMDDHHMMSS.0Z, where

YYYY – four digits of the year
MM - two-digit month (01=January, etc.)
DD - two-digit day of month (01 through 31)
hh - two digits of hour (00 through 23) (am/pm NOT allowed)
mm - two digits of minute (00 through 59)
ss - two digits of second (00 through 59)

The date 1997-07-16 19:20:30 in the GeneralizedTime format will look as follows:
19970716192030.0Z
Timestamp The Timestamp data type represents the date and time values as the number of 100-nanosecond units that have elapsed since the 0 hour on January 1, 1601, 00:00:00 UTC.
Interval

The time interval is expressed by number of 100 nanosecond steps.
Note: The result of subtraction of two date-time values will be an interval value.

Supported string literal formats to define date-time

UTC, GeneralizedTime and Timestamp are data types that store combined date and time values. The following tables list the supported string literal formats to define date and time.

Date Formats* Description
[0]4/15/[19]96 - (mdy) 
[0]4-15-[19]96 - (mdy)
[0]4.15.[19]96 - (mdy)
15/[0]4/[19]96 - (dmy)
15/[19]96/[0]4 - (dym)
[19]96/15/[0]4 - (ydm)
[19]96/[0]4/15 - (ymd)

You can specify a date with a numeric month. For example, 5/20/97 represents the twentieth day of May 1997. When you use the numeric date format, specify the month, day, and year in a string that uses slash marks (/), hyphens (-), or periods (.) as separators.

In the notations (mdy), (dym), (ymd)

  • m - month

  • d - day

  • y - year

Apr[il] [15][,] 1996 
Apr[il] 15[,] [19]96
Apr[il] 1996 [15]
[15] Apr[il][,] 1996
15 Apr[il][,][19]96
15 [19]96 apr[il]
[15] 1996 apr[il]
1996 APR[IL] [15]
1996 [15] APR[IL]

You can specify a date using the full month name. For example, April or the month abbreviation (Apr) specified in the current language. Commas are optional and capitalization is ignored. If the day is missing, the first day of the month is used.

Time Formats* Description
14:30 - (h:m) 
14:30[:20] - (h:m:s)
4am
4 PM
  • h - hours (0 through 23)

  • m - minutes (0 through 59)

  • s - seconds (0 through 59)

* Characters enclosed in square brackets are optional.

To define date and time values, you should follow the syntax below:

"date_format time_format"

where,
date_format - literal representation of date
time_format - literal representation of time

For example

"2010-12-15 12:25:00"
"11.03.2009 4 PM"
"3/7/1982 12:30"

If you need to explicitly define that a string represents a date-time value, you can use either type conversion or the explicit predicate definition. In the following example, we use the explicit predicate definition to specify the conversion of the string containing a date-time value into the UTC format.

UPDATE  "CN=MyMeeting,DC=company" 
SET  $meetingEndTime = Utc "2010-12-15 12:25"

Supported literal formats to define interval

Interval is used to specify a period of time, for example 2 months, 5 days, 200 minutes, etc. The unit of measure of the Interval type is 100 nanoseconds. E.g. 1 second = 10000000 intervals. To avoid conversion of time values into the Interval values, you can use simple and understandable literal formats to specify them. You can use time formats to define Interval values. For example:

interval "03:25"

defines a time interval of 3 hours, 25 minutes. Another example:

interval "12:23:45"

defines time interval of 12 hours, 23 minutes, 45 seconds.

You can also use the following notation to describe time intervals

interval "duration_count duration_type"

where
duration_count - the number defining the quantity of duration_type
duration_type - defines the type of the time interval. Can be one of these values: year(s), month(s), day(s), hour(s),minute(s), second(s).

In order to define an interval of 5 hours, you can write the following code.

interval "5 hours"

Or, the string

interval "2 hours" + interval "56 minutes" + interval "23 seconds"

defines an interval of 2 hours, 56 minutes and 23 seconds.

Mathematic operators (+,-) can be used to work with interval values.

The Interval type can be used to modify date-time values. Values of the Interval data type can be added to or subtracted from the value of any date-time type. The result of these calculations will be a value of the date-time type. For example, if you deduct an interval of 3 days from a date, you will receive a 3 days old date. If you want to find all entries created for the last 3 days, you can use the following expression:

SELECT * FROM "OU=PEOPLE" WHERE $whenCreated > CURRENT_DATE - interval "3 days" 

The CURRENT_DATE function returns the current date.

Data Type Conversion

When working with LDAP-SQL, you often may need to convert data of one type to another. This can be achieved by using the CAST function. The following example retrieves the entries that have a 5 in the beginning of the countryCode attribute:

SELECT $countryCode FROM "DC=Company,DC=com" 
WHERE $countryCode IS NOT NULL 
AND SUBSTRING(CAST($countryCode AS String) FROM 1 FOR 1) = '5'

In this example, we use the CAST function to convert integer attribute countryCode to a string. After that, this string is passed to the SUBSTRING function that returns the first character of the string.

If the value of an expression or function is assigned to an attribute, an attempt to automatically convert this value into the type of assigned attribute is made. If such conversion is not possible, an error occurs. In the next example, the whenCreated attribute of the GeneralizedTime type is automatically converted to the String type.

UPDATE "CN=Peter,OU=Developers,DC=Company" 
SET $description=$whenCreated

Comments

There are two types of comments in LDAP-SQL: single-line and multiline. Single-line comments are set with the help of two hyphens (--) and end with an end-of-line symbol. For example,

-- Comment text

Multiline comments are specified with the help of symbols /* and */. Text placed between /* and */ is not executed and can span multiple lines.

Multiline comments also support nested comments. If combination of symbols /* is used within the existing comments, it is considered as the beginning of the nested comment and, therefore, requires symbols */ that close this comment. An example of a complex comment:

/* complex comment /* nested comment */
end of the complex comment */