Use query parameters

Queries in Knowledge Studio support query parameters. Once written, queries are static, parameters in the query allow parts of the query to be dynamic. A query parameter is a variable in the query for which the value is defined when the query is run. This allows users to run the same query with different values without having to modify the query.

For example, you can write a query to find all directly related entities to a person: MATCH (p:Person)-[]-(n) WHERE p.Name = "John Doe" RETURN n. Query parameters replace John Doe with a variable $name that can be configured to be any name: MATCH (p:Person)-[]-(n) WHERE p.Name = $name RETURN n. The Parameters pane in the query view allows you to define the $name parameter and then change the value without modifying the query.

Parameter Type	Description
String	Any set of alphanumeric characters.
Number	Matches graph properties of any number type except Big Integer. Note: Knowledge Studio only supports safe integers that fall between -9007199254740991(minimum)and 9007199254740991(maximum). Numbers that fall outside of this range will be incorrect due to rounding so will not match against Big Integer fields in the knowledge graph.
Geometry	Set geometries for use in any of the spatial operators supported in queries. Only supports rectangle geometries at this time.
Date Only	Date values only with no time values. Learn more about using date-time values in queries
Time Only	Time only values up to seconds only precision with no date values. Learn more about using date-time values in queries
Date	Date and time value precision in seconds (low precision) or milliseconds (high precision). Learn more about using date-time values in queries
Timestamp Offset	Date, time, and offset from the Coordinated Universal Time (UTC) zone. Learn more about using date-time values in queries
Entity	Entities in the knowledge graph.
Relationship	Relationships in the knowledge graph.

Configure new parameters

The configure pane lets you define and initialize the parameters in your query. Each parameter used in the query must be configured for the query to run. Parameters can be one of the following types:

String parameter

Configure a String parameter.

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select String from theType drop-down
6. Enter the string in the input box to use as the initial Value for the parameter . The default is Single value, see Define value list to set a list of values for the parameter.
7. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Number parameter

Configure a Number parameter

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Number from theType dropdown
6. Enter the number in the input box to use as the initial Value for the parameter . The default is Single value, see Define value list to set a list of values for the parameter.
7. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Geometry parameter

Configure a Geometry parameter.

Learn more about spatial operators in queries.

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Geometry from theType dropdown
6. Click Set Geometry to define the initial Value for the parameter . The default is Single value , see Define value list to set a list of values for the parameter. .

   The geometry sketch modal opens.

7. Click the rectangle tool in the graphics toolbar.
8. Click and drag on the map to draw a rectangle around the area of interest.

   If configuring a list of geometries, this step for each geometry.

9. Optionally, select the geometry using one of the following methods on the graphics toolbar.
   • Select feature - Click the feature to select it.
   • Select by rectangle - Click the map and drag a rectangle across the feature to select it.
   • Select by lasso - Click the map or link chart and draw with the pointer to create a freehand shape selection.
10. Optionally modify or remove a feature:
    • resize the feature by clicking on one of the rectangles on the edges or corners and dragging to resize.
    • move the feature by clicking anywhere in the feature and dragging it to a new location on the map.
    • Click Delete feature in the graphics toolbar to remove the feature.
    • Click Clear to reset the map.
11. Click Ok
12. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Date Only

Configure a Date Only parameter.

Learn more about using date-time values in queries

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Date Only from the Type dropdown
6. Set the date to use for the Value. The default is Single value, see Define value list to set a list of values for the parameter. Define the date using one of the following methods:
   • Type the date in the input box in MM/DD/YYYY format.
   • Click input box and select a date using the calendar.
7. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Time Only

Configure a Time Only parameter.

Learn more about using date-time values in queries

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Time Only from the Type dropdown
6. Set the time to use for theValue. . The default is Single value, see Define value list to set a list of values for the parameter. Define the time using one of the following methods:
   • Type the time in the input box in HH:MM:SS.SSS format.
   • Optionally, define the time using the time picker.
7. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Date

Configure a Date parameter.

Learn more about using date-time values in queries

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Date from theType dropdown
6. Set the date and time for the Value. The default is Single value, see Define value list to set a list of values for the parameter. Define the date using one of the following methods:
   • Type the date in the input box in MM/DD/YYYY format.
   • Click input box and select a date using the calendar.
7. Define the time using one of the following methods:
   • Type the time in the input box in HH:MM:SS.SSS format.
   • Optionally, define the time using the time picker.
8. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Timestamp offset parameter

Configure a Timestamp Offset parameter.

Learn more about using date-time values in queries

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Timestamp Offset from theType dropdown
6. Set the date, time and UTC offset for the Value. The default is Single value, see Define value list to set a list of values for the parameter. Define the date using one of the following methods:
   • Type the date in the input box in MM/DD/YYYY format.
   • Click input box and select a date using the calendar.
7. Define the time using one of the following methods:
   • Type the time in the input box in HH:MM:SS.SSS format.
   • Optionally, define the time using the time picker.
8. Enter the number of minutes for the time zone offset in UTC offset in minutes.

   The default is zero. The minimum value is -720 (-12:00 hours) and the maximum value is 840 (+14:00 hours)

9. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Entity or Relationship

Configure an Entity or Relationship parameter. Configuring an entity or relationship parameter uses the unique identifier for the entity or relationship as the parameter.

For example MATCH (p:Person)-[]-(m) WHERE ID(p) = $entityOrRelationshipUniqueID

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. Click Create new parameter

   The new Parameter form opens.

3. Name your parameter.
   1. Click the options menu next to the Parameter heading.
   2. Click Rename.
   3. Type a descriptive name for the parameter in the Title box.
   4. Click Apply.

   The heading for the parameter is updated to the new name.

4. Define the parameter in the Bind Parameter input using one of the following methods:
   • Type the name of the parameter in the input box.
   • If you have written a query that contains parameters, select the parameter from the drop-down.
5. Select Entity or Relationshiprom theType dropdown.
6. Start typing the name of the entity in the input box to defined the entity or relationship to use for the Value. The default is Single value, see Define value list to set a list of values for the parameter.

   A drop-down list with the top five matched records will appear. The list will update as you type.

7. Select the record from the drop-down list.
8. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Use lists for parameter values

Any parameter can be a list of values, but the list can only contain one type of values. For example, to find all people who have common last names, you might use the query MATCH (p:People) where n.lastName in $lastNameList RETURN n and define lastNameList as a String list containing Smith, Jones, and Johnson using the parameters pane.

If you have a delimited list of values, such as a comma separated list of names, use List from Text to add values to the list.

Define list of values

You can use the same set of steps used to define a value to create a list of values by selecting Value List instead of Single Value. After defining each value, add it to the list, or manage the list of values to remove items.

1. Click Value List to define a list of values for the parameter.
2. Use the same input method as the single value for the type selected (starting at step six). Or see a summary of the steps for each type in the table below.

   String	Type the string into the input field.
   Number	Type the number into the input field Note: Knowledge Studio only supports safe integers that fall between -9007199254740991(minimum)and 9007199254740991(maximum). Numbers that fall outside of this range will be incorrect due to rounding so will not match against Big Integer fields in the knowledge graph.
   Geometry	Click Set Geometry and draw multiple geometries
   Date Only	Type the date in MM/DD/YYYY format or use the calendar to enter the date.
   Time Only	Type the time in HH:MM:SS.sss format or use the time picker to enter the time
   Date	Type the date in HH:MM:SS.sss format or use the calendar to enter the date. Type the time in MM/DD/YYYY format or use the time picker to enter the time
   Timestamp Offset	Type the date in HH:MM:SS.sss format or use the calendar to enter the date. Type the time in MM/DD/YYYY format or use the time picker to enter the time. Type the UTC offset in minutes.
   Entity	Use the input field to find and select an entity.
   Relationship	Use the input field to find and select a relationship.

3. Click Add
4. Repeat steps one and two until all values are added to the list.
5. Optionally, manage the values in the list.
   • Click the Values heading to show the values in the list.
   • Click Clear next to a value to remove it from the list.
   • Click Clear to clear the list.
   • Click Copy to copy the values in the list to the system clipboard.
6. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Custom list from text

If you have many values to add to a list, you can use the List from text feature to generate the list of values. List from text accepts a delimited list, such as a comma separated list of names, and generates a list of values for the parameter of the type you've chosen (see the list ofsupported types).

1. Click List from text.

   The List from text modal opens.

2. Type character or characters that separate the values in your list as the Delimiter input. The default is a comma. If the list is delimited by a tab or new lines (Enter) click the appropriate option.
3. Paste the delimited list in the text box.

   The parameter type will be listed above the text box. All values in the list must match this type.

4. Click Generate List.

   The Result List is generated below the text box.

5. Optionally click the result list to view the results
   1. Optionally click the X next to a value to remove it from the list.
6. Optionally click Clear to clear all the values from the list
7. Click Add Values to List to add the generate values to the parameter list.
8. Click Apply to run the query with the configured parameters.

The query results will update based the new parameter values.

Remove parameter

Configured parameters can be removed from the query.

1. On the context toolbar, click Parameters.

   The Parameters pane opens.

2. If the pane opens to the edit tab click the Configure tab.
3. Click the Options menu next to the parameter name.

   The options menu opens.

4. Click Delete.

   The parameter is removed.

Note:

If the query still contains the parameter it will return an error when run unless the parameter is removed from the query or reconfigured.

Edit values

If parameters have been configured for a stored query, when that query is opened the Parameters pane automatically opens to the Edit Values tab.

1. If the Parameters pane is not open, click Parameters on the context toolbar.

   The Parameters pane opens. The parameters configured for the query will be listed.

2. Update the value based on the Type of the parameter.

   The type of each parameter will be shown below the heading. If the parameter uses a list of values List will be included after the type. See Define value list to update values in a list. The current values used in the query will be shown in the input elements for each parameter. The steps for each type are summarized below.

   String	Type the string into the input field.
   Number	Type the number into the input field Note: Knowledge Studio only supports safe integers that fall between -9007199254740991(minimum)and 9007199254740991(maximum). Numbers that fall outside of this range will be incorrect due to rounding so will not match against Big Integer fields in the knowledge graph.
   Geometry	Click Set Geometry and draw multiple geometries
   Date Only	Type the date in MM/DD/YYYY format or use the calendar to enter the date.
   Time Only	Type the time in HH:MM:SS.sss format or use the time picker to enter the time
   Date	Type the date in HH:MM:SS.sss format or use the calendar to enter the date. Type the time in MM/DD/YYYY format or use the time picker to enter the time
   Timestamp Offset	Type the date in HH:MM:SS.sss format or use the calendar to enter the date. Type the time in MM/DD/YYYY format or use the time picker to enter the time. Type the UTC offset in minutes.
   Entity	Use the input field to find and select an entity.
   Relationship	Use the input field to find and select a relationship.

3. Click Apply to run the query with the updated values.

The query results will update based the new parameter values.