Softerra LDAP Administrator Help | Show AllHide All |
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.
Type | Characters |
---|---|
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.
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.
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 Sequence | Interpretation |
---|---|
\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 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 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. |
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 Type | Description |
---|---|
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 970716192030.0Z |
GeneralizedTime |
The GeneralizedTime date type represents date and time values in the format
YYYYMMDDHHMMSS.0Z, where
YYYY – four digits of the year 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.
|
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) | 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)
|
Apr[il] [15][,] 1996 | 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) |
|
* 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"
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. |
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
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 */