Global System Query Functions

Created: July 13, 2021 | Updated: August 28, 2021 | Applies to versions: 4 and 5

Now reading version 4.0. For the latest, read: Global System Query Functions for version 5

This documentation page references Altium NEXUS/NEXUS Client (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

Parent page: Working with the Query Language

Global system query functions shown in the Query Helper dialog

Underlying Altium NEXUS's schematic and PCB editors is a powerful query engine. By entering queries into this engine you can logically scope precisely those objects you require.

A query is a string you enter using specific keywords and syntax, which will return the targeted objects. There are many keywords available, allowing you to target objects by their type, their properties, or both.

For a detailed overview of using the query language, see Working with the Query Language.

This reference page details the query language keywords available in the schematic, PCB, and library documents in Altium NEXUS. For help on a specific query keyword, use the following collapsible sections or highlight (or click inside) any given keyword - in the Query Helper, a Filter panel, or the Query field of a PCB design rule - and press F1 to access its section right away.

Arithmetic Functions

ABS

Summary

Returns a (real) number whose value is equal to the absolute value of the parameter's numeric value. If that numeric value is positive, the number returned has the same value; otherwise the number returned is equal to the parameter's numeric value multiplied by -1.

Syntax

ABS(X : Number / Numeric_String) : Number

Example Usage

ABS(2.3)
Returns 2.3.

ABS(-7.2)
Returns 7.2.

CEIL

Summary

Returns an integral number, whose value depends upon the nature of the parameter's numeric value. If that numeric value is an exact integer, the number returned has exactly the same value; otherwise the number returned is the smallest integer that is larger in value than the parameter's numeric value.

Syntax

CEIL(X : Number / Numeric_String) : Number

Example Usage

CEIL(5.0)
Returns 5.

CEIL(5.33)
Returns 6.

CEIL(-5.0)
Returns -5.

CEIL(-5.33)
Returns -5.

FLOOR

Summary

Returns an integral number, whose value depends upon the nature of the parameter's numeric value. If that numeric value is an exact integer, the number returned has exactly the same value; otherwise the number returned is the largest integer that is smaller in value than the parameter's numeric value.

Syntax

FLOOR(X : Number / Numeric_String) : Number

Example Usage

FLOOR(5.0)
Returns 5.

FLOOR(5.33)
Returns 5.

FLOOR(-5.0)
Returns -5.

FLOOR(-5.33)
Returns -6.

FRAC

Summary

Returns a (real) number, whose value depends upon the nature of the parameter's numeric value:

If that numeric value is positive but is not an exact integer, the number returned is the difference between the parameter's numeric value and the largest integer that is smaller in value than the parameter's numeric value.
If that numeric value is negative but is not an exact integer, the number returned is the difference between the parameter's numeric value and the smallest integer that is larger in value than the parameter's numeric value.
If the parameter's numeric value is an exact integer, the number returned is 0.

Syntax

FRAC(X : Number / Numeric_String) : Number

Example Usage

FRAC(5.0)
Returns 0.

FRAC(5.33)
Returns 0.33.

FRAC(-5.0)
Returns 0.

FRAC(-5.33)
Returns -0.33.

IIF

Summary

This is a special purpose construction which contains three queries. The value of the first query (between the opening bracket and the first comma) is evaluated. If that is True, the second query (between the commas) is returned; otherwise, the third query (between the second comma and closing bracket) is returned.

This Keyword is similar in concept to "If ... Then ... Else ..." constructions provided with many computer programming languages.

Syntax

IIF(L : Boolean Query , A : Query , B : Query)

L, A, and B are all strings which each specify some Query; L needs to be a Boolean Query (i.e. of a nature that returns either a True or False result).

IIF(L,A,B) has an identical outcome to the Query comprised of ((L = True) And A) Or ((L = False) And B). As such, it is especially useful when L is of a complex nature, as it only needs to be specified once.

Example Usage

IsArc And IIF(ArcStopAngle - ArcStartAngle >= 0 , ArcStopAngle - ArcStartAngle Between 30 And 60 , ArcStartAngle - ArcStopAngle Between 300 And 330)
Returns all arcs that have an arc length which is greater than or equal to 30 degrees and less than or equal to 60 degrees. (The arc length property of an arc is an angle that is determined by subtracting its Start Angle property from its Stop Angle property. A complicating consideration is that it is possible for an arc's Stop Angle property to be smaller than its Start Angle property, but this Query correctly evaluates the true arc length property for all possible arc objects.)

IsComponent And IIF(Layer = 'Top Layer' , Rotation <> 0 , Rotation <> 180)
Returns all components that are on the top side of the PCB whose Rotation property is not 0 degrees, and all components that are on the bottom side of the PCB whose Rotation property is not 180 degrees. (Component objects can only reside on the Top signal layer or Bottom signal layer, so any component which is not on the Top signal layer must then be on the Bottom signal layer instead.)

INT

Summary

Returns an integral number, whose value depends upon the nature of the parameter's numeric value:

If that numeric value is positive but is not an exact integer, the number returned is the largest integer that is smaller in value than the parameter's numeric value.
If that numeric value is negative but is not an exact integer, the number returned is the smallest integer that is larger in value than the parameter's numeric value.
If that numeric value is an exact integer, the number returned has exactly the same value.

Syntax

INT(X : Number / Numeric_String) : Number

Example Usage

INT(5.0)
Returns 5.

INT(5.33)
Returns 5.

INT(-5.0)
Returns -5.

INT(-5.33)
Returns -5.

Tips

This is an alias for the TRUNC arithmetic function.

MAX

Summary

Returns a (real) number whose value is equal to the maximum value of all of the parameters provided. Each parameter must be either a number, or a numeric string, and any number of parameters can be provided.

Syntax

MAX(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

MAX(2)
Returns 2.

MAX(7,2,3)
Returns 7.

Tips

At least one parameter must be provided.

MIN

Summary

Returns a (real) number whose value is equal to the minimum value of all of the parameters provided. Each parameter must be either a number, or a numeric string, and any number of parameters can be provided.

Syntax

MIN(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

MIN(2)
Returns 2.

MIN(7,2,3)
Returns 2.

Tips

At least one parameter must be provided.

POWER

Summary

Returns a (real) number whose value is equal to the first parameter's numeric value raised to the power of the second parameter's numeric value.

Syntax

POWER(X : Number / Numeric_String , Y : Number / Numeric_String) : Number

Example Usage

POWER(3,2)
Returns 9.

POWER(32,0.2)
Returns 2.

POWER(16,-0.5)
Returns 0.25.

ROUND

Summary

Returns an integral number, whose value depends upon the nature of the parameter's numeric value:

If that numeric value is an exact integer, the number returned has exactly the same value.
If that numeric value is not an exact integer, the number returned is the integer which is closest in value to the parameter's numeric value. Positive numbers which are exactly midway between adjacent integers are rounded upwards, while negative numbers which are exactly midway between adjacent integers are rounded downwards.

Syntax

ROUND(X : Number / Numeric_String) : Number

Example Usage

ROUND(5.0)
Returns 5.

ROUND(5.33)
Returns 5.

ROUND(5.5)
Returns 6 (Rounded upwards).

ROUND(5.66)
Returns 6.

ROUND(-5.0)
Returns -5.

ROUND(-5.33)
Returns -5.

ROUND(-5.5)
Returns -6 (Rounded downwards).

ROUND(-5.66)
Returns -6.

SIGN

Summary

Returns sign value of the supplied parameter. That is, it returns an integral number, whose value depends upon the nature of the parameter's numeric value:

If that numeric value is positive, the number returned is 1.
If that numeric value is negative, the number returned is -1.
If that numeric value is exactly zero, the number returned is 0.

Syntax

SIGN(X : Number / Numeric_String) : Number

Example Usage

SIGN(5.33)
Returns 1.

SIGN(-5.33)
Returns -1.

SIGN(0)
Returns 0.

SQR

Summary

Returns a (real) number whose value is equal to the square of the parameter's numeric value.

Syntax

SQR(X : Number / Numeric_String) : Number

Example Usage

SQR(2)
Returns 4.

SQR(14.1)
Returns 198.81.

SQR(-1.5)
Returns 2.25.

SQRT

Summary

Returns a (real) number whose value is equal to the (positive) square root of the parameter's numeric value.

Syntax

SQRT(X : Number / Numeric_String) : Number

Example Usage

SQRT(4)
Returns 2.

SQRT(10)
Returns 3.1623.

TRUNC

Summary

Returns an integral number, whose value depends upon the nature of the parameter's numeric value:

If that numeric value is positive but is not an exact integer, the number returned is the largest integer that is smaller in value than the parameter's numeric value.
If that numeric value is negative but is not an exact integer, the number returned is the smallest integer that is larger in value than the parameter's numeric value.
If that numeric value is an exact integer, the number returned has exactly the same value.

Syntax

TRUNC(X : Number / Numeric_String) : Number

Example Usage

TRUNC(5.0)
Returns 5.

TRUNC(5.33)
Returns 5.

TRUNC(-5.0)
Returns -5.

TRUNC(-5.33)
Returns -5.

Tips

This is an alias for the INT arithmetic function.

ZERO

Summary

Returns an integral number whose value is either 0 or 1, depending upon the parameter's numeric value. If that numeric value is zero, the number returned is 0; otherwise the number returned is 1.

Syntax

ZERO(X : Number / Numeric_String) : Number

Example Usage

ZERO(5.33)
Returns 1.

ZERO(-5.33)
Returns 1.

ZERO(0)
Returns 0.

Trigonometry Functions

ACOS

Summary

Returns a (real) number whose value is equal to the angle of the inverse cosine of the number specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

ACOS(X : Number / Numeric_String) : Number

Example Usage

ACOS(0)
Returns 1.5708.

ACOS(0.5)
Returns 1.0472.

ACOS(1)
Returns 0.

ASIN

Summary

Returns a (real) number whose value is equal to the angle of the inverse sine of the number specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

ASIN(X : Number / Numeric_String) : Number

Example Usage

ASIN(0)
Returns 0.

ASIN(0.5)
Returns 0.5236.

ASIN(1)
Returns 1.5708.

ATAN

Summary

Returns a (real) number whose value is equal to the angle of the inverse tangent of the number specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

ATAN(X : Number / Numeric_String) : Number

Example Usage

ATAN(0)
Returns 0.

ATAN(1)
Returns 0.7854.

ATAN(2.5)
Returns 1.1903.

COS

Summary

Returns a (real) number whose value is equal to the cosine of the angle specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

COS(X : Number / Numeric_String) : Number

Example Usage

COS(0)
Returns 1.

COS(0.8)
Returns 0.6967.

COS(1.57)
Returns 0.0008.

COSH

Summary

Returns a (real) number whose value is equal to the hyperbolic cosine of the parameter's numeric value.

Syntax

COSH(X : Number / Numeric_String) : Number

Example Usage

COSH(TextHeight / TextWidth) < 70.5
Returns objects for which the hyperbolic cosine of the ratio of their TextHeight distance to their TextWidth distance is less than 70.5. (That is equivalent to returning objects for which the ratio of their TextHeight distance to their TextWidth distance is less than 4.9487).

(TextHeight / TextWidth) >= COSH(2.3)
Returns objects for which the ratio of their TextHeight distance to their TextWidth distance is equal to, or greater than, the hyperbolic cosine of 2.3 (which is 5.0372).

COTAN

Summary

Returns a (real) number whose value is equal to the cotangent of the angle specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

COTAN(X : Number / Numeric_String) : Number

Example Usage

COTAN(0.1)
Returns 9.9666.

COTAN(0.8)
Returns 0.9712.

COTAN(1.57)
Returns 0.0008.

SIN

Summary

Returns a (real) number whose value is equal to the sine of the angle specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

SIN(X : Number / Numeric_String) : Number

Example Usage

SIN(0)
Returns 0.

SIN(0.8)
Returns 0.7174.

SIN(1.57)
Returns 1.0.

SINH

Summary

Returns a (real) number whose value is equal to the hyperbolic sine of the parameter's numeric value.

Syntax

SINH(X : Number / Numeric_String) : Number

Example Usage

SINH(TextWidth / TextHeight) < 0.17
Returns objects for which the hyperbolic sine of the ratio of their TextWidth distance to their TextHeight distance is less than 0.17. (That is equivalent to returning objects for which the ratio of their TextWidth distance to their TextHeight distance is less than 0.1692).

(TextWidth / TextHeight) >= SINH(0.2)
Returns objects for which the ratio of their TextWidth distance to their TextHeight distance is equal to, or greater than, the hyperbolic sine of 0.2 (which is 0.2013).

TAN

Summary

Returns a (real) number whose value is equal to the tangent of the angle specified by the parameter's numeric value; that angle is in units of radians (and not degrees).

Syntax

TAN(X : Number / Numeric_String) : Number)

Example Usage

TAN(0)
Returns 0.

TAN(0.8)
Returns 1.0296.

TAN(1.57)
Returns 1255.7656.

TANH

Summary

Returns a (real) number whose value is equal to the hyperbolic tangent of the parameter's numeric value.

Syntax

TANH(X : Number / Numeric_String) : Number

Example Usage

TANH(TextWidth / TextHeight) < 0.17
Returns objects for which the hyperbolic tangent of the ratio of their TextWidth distance to their TextHeight distance is less than 0.17. (That is equivalent to returning objects for which the ratio of their TextWidth distance to their TextHeight distance is less than 0.1717).

(TextWidth / TextHeight) >= TANH(0.2)
Returns objects for which the ratio of their TextWidth distance to their TextHeight distance is equal to, or greater than, the hyperbolic tangent of 0.2 (which is 0.1974).

Exponential and Logarithmic Functions

EXP

Summary

Returns a (real) number whose value is equal to e raised to the power of the parameter's numeric value. (The number e is the base of natural logarithms, and is approximately equal to 2.7183).

Syntax

EXP(X : Number / Numeric_String) : Number

Example Usage

EXP(0)
Returns 1.

EXP(1)
Returns 2.7183.

Summary

Returns a (real) number whose value is equal to the base 10 logarithm of the parameter's numeric value.

Syntax

LG(X : Number / Numeric_String) : Number

Example Usage

LG(1)
Returns 0.

LG(10)
Returns 1.

LG(25)
Returns 1.3979.

Summary

Returns a (real) number whose value is equal to the natural (or base e) logarithm of the parameter's numeric value. (The number e is 2.7183).

Syntax

LN(X : Number / Numeric_String) : Number

Example Usage

LN(1)
Returns 0.

LN(2)
Returns 0.6931.

LN(10)
Returns 2.3026.

LOG

Summary

Returns a (real) number whose value is equal to the base 2 logarithm of the parameter's numeric value.

Syntax

LOG(X : Number / Numeric_String) : Number

Example Usage

LOG(1)
Returns 0.

LOG(2)
Returns 1.

LOG(8)
Returns 3.

LOG(10)
Returns 3.3219.

Aggregate Functions

AVG

Summary

Returns a (real) number whose value is equal to the average value of all of the parameters provided. Each parameter must be either a number, or a numeric string, and any number of parameters can be provided.

Syntax

AVG(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

AVG(2)
Returns 2.

AVG(7,2,3)
Returns 4.

Tips

At least one parameter must be provided.

MAX

Summary

Syntax

MAX(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

MAX(2)
Returns 2.

MAX(7,2,3)
Returns 7.

Tips

At least one parameter must be provided.

MIN

Summary

Syntax

MIN(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

MIN(2)
Returns 2.

MIN(7,2,3)
Returns 2.

Tips

At least one parameter must be provided.

PROD

Summary

Returns a (real) number whose value is equal to the product of all of the parameters provided. Each parameter must be either a number, or a numeric string, and any number of parameters can be provided.

Syntax

PROD(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

PROD(2)
Returns 2.

PROD(7,2,3)
Returns 42.

Tips

At least one parameter must be provided.

SUM

Summary

Returns a (real) number whose value is equal to the sum of all of the parameters provided. Each parameter must be either a number, or a numeric string, and any number of parameters can be provided.

Syntax

SUM(N1 : Number / Numeric_String, [N2] : Number / Numeric_String, ...) : Number

Example Usage

SUM(2)
Returns 2.

SUM(7,2,3)
Returns 12.

Tips

At least one parameter must be provided.

System Functions

Copy

Summary

Returns a substring of a string. It is possible to specify how many characters will be within the substring returned, and the location within the string which will be the first character of the substring returned.

Syntax

Copy(S : String , Index : Integer , Count : Integer) : String

S is a string-type expression. Index and Count are integer-type expressions. Copy returns a substring containing Count characters starting at S[Index].

If Index is larger than the length of S, Copy returns an empty string.

If Count specifies more characters than are available, only the characters from S[Index] to the end of S are returned.

Example Usage

Copy('Cats and dogs',1,1)
Returns 'C'. (Return 1 character, from the 1st location within the string).

Copy('Cats and dogs',2,1)
Returns 'a'. (Return 1 character, from the 2nd location within the string).

Copy('Cats and dogs',13,1)
Returns 's'. (Return 1 character, from the 13th location within the string).

Copy('Cats and dogs',14,1)
Returns '' (an empty string). (Return 1 character, from the 14th location within the string; however, there are only 13 characters within the string, so an empty string is returned).

Copy('Cats and dogs',1,2)
Returns 'Ca'. (Return 2 characters, starting from the 1st location within the string).

Copy('Cats and dogs',2,2)
Returns 'at'. (Return 2 characters, starting from the 2nd location within the string).

Copy('Cats and dogs',12,2)
Returns 'gs'. (Return 2 characters, starting from the 12th location within the string).

Copy('Cats and dogs',13,2)
Returns 's'. (Return 2 characters, starting from the 13th location within the string; however, there are only 13 characters within the string, so only 1 character gets returned).

Copy('Cats and dogs',15,2)
Returns '' (an empty string). (Return 2 characters, starting from the 15th location within the string; however, there are only 13 characters within the string, so an empty string gets returned).

Copy('Cats and dogs',1,6)
Returns 'Cats a'. (Return 6 characters, starting from the 1st location within the string).

Copy('Cats and dogs',5,9)
Returns ' and dogs'. (Return 9 characters, starting from the 5th location within the string).

Copy('Cats and dogs',8,5)
Returns 'd dog'. (Return 5 characters, starting from the 8th location within the string).

Copy('Cats and dogs',8,6)
Returns 'd dogs'. (Return 6 characters, starting from the 8th location within the string).

Copy('Cats and dogs',8,7)
Returns 'd dogs'. (Return 7 characters, starting from the 8th location within the string; however, there are only 13 characters within the string, so only 6 characters get returned).

Length

Summary

Returns the number of characters contained within a string.

Syntax

Length(S : String) : Integer

S is the string whose character count is to be returned.

Example Usage

Length(Name) Between 4 And 7
Returns objects that have a Name property which contains between 4 and 7 characters.

Length('Cat')
Returns 3.

Length('Darryll')
Returns 7.

Length('Cats and dogs')
Returns 13.

Length('')
Returns 0.

Pos

Summary

Returns the index value of the first character in a specified substring that occurs in a given string.

Syntax

Pos(Substr : String , S : String) : Integer

Pos searches for a substring, Substr, within a string, S. Substr and S are string-type expressions. An integer value is returned that is the index of the first character of Substr.

Pos is case-sensitive. If Substr is not found, Pos returns zero.

Example Usage

Pos('T',Name) = 1
Returns all objects that have a Name property whose associated string first contains 'T' at its first position; 'T1' and 'Time Table' are examples of such strings. ('T' is located twice within the string 'Time Table', but the first location of this is at its first position.)

Pos('A',Name) = 2
Returns all objects that have a Name property whose associated string first contains 'A' at its second position; 'RA1' and 'CABLE CHART' are examples of such strings.

Pos('B',Name) = 0
Returns all objects that have a Name property whose associated string does not contain 'B' at any position; 'D1' and 'Time Table' are examples of such strings. (The string of 'Time Table' contains 'b' at its eighth position, but Pos is case-sensitive.)

Pos('D',Name) > 0
Returns all objects that have a Name property whose associated string contains 'D' at at least one position and at any location(s); 'Data Chart', 'U1D', and 'Install either D1 and D2 or D3 and D4, but never install all of these.' are examples of such strings.

Pos('Con',Name) = 1
Returns all objects that have a Name property whose associated string first contains 'Con' at its first, second, and third positions; 'Concatenate' is an example of a such string. (The first location of 'Con' within 'Concatenate' is the first three characters of this; the first character within 'Con' is 'C', and its location is the first character of 'Concatenate'.)

Pos('ate',Name) = 5
Returns all objects that have a Name property whose associated string first contains 'ate' at its fifth, sixth, and seventh positions; 'Concatenate' is an example of a such string. (The first location of 'ate' within 'Concatenate' is the fifth through to seventh characters of this; the first character within 'ate' is 'a', and its location is the fifth character of 'Concatenate'.)

Pos('ate',Name) = 0
Returns all objects that have a Name property whose associated string does not contain 'ate' anywhere; 'C1' and 'TIME:' are examples of such strings.

Pred

Summary

Returns a (real) number whose value is equal to parameter's numeric value less 1.0.

Syntax

Pred(X : Number / Numeric_String) : Number

Example Usage

Pred(4.1)
Returns 3.1.

Pred(41.313)
Returns 40.313.

Random

Summary

Returns a random number between 0 and X-1.

Syntax

Random(X) : Number

Example Usage

Random(10)
Returns a value between 0 and 9.

Random(100)
Returns a value between 0 and 99.

Succ

Summary

Returns a (real) number whose value is equal to parameter's numeric value plus 1.0.

Syntax

Succ(X : Number / Numeric_String) : Number

Example Usage

Succ(2.1)
Returns 3.1.

Succ(41.313)
Returns 42.313.

Printer-friendly version

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.