Variable

1. While in a Part Studio, click to open the Variable dialog box.

   

2. In the dialog:

   1. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   2. Select a type:
      • Length - A numeric value representing a length (decimal, integer, fraction)
      • Angle - A numeric value representing an angle (decimal, integer, fraction)
      • Number - A numeric value (decimal, integer, fraction)
      • Any - Any of the above, a numeric value with different units, or a FeatureScript value such as boolean, map, array, string, or a function. See https://cad.onshape.com/FsDoc/variables.html#standard-types and examples below.
   3. Enter a value (and optionally, units for Length, Angle, and Any).
   4. Enter a custom description for your variable.
3. Click .

1. While in a Part Studio, click to open the Variable dialog box, then click Measured:

   

2. In the dialog:
   1. Select a type:
      • Distance - A numeric value representing a distance (decimal, integer, fraction)
      • Length - A numeric value representing a length (decimal, integer, fraction)
      • Diameter - A numeric value representing a diameter (decimal, integer, fraction)

   2. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   3. Select entities to measure between.
   4. Fill out the remaining fields according to your preferences.
3. Click .

The From table option in the Variable feature enables users to create a single variable that stores a subset of rows and columns from the CSV table. The Row options filter the rows and determine the Result type (Single value, Array, or Map) of the variable. The Column options then filter each row and determine the type of each entry in the final variable.

1. While in a Part Studio, click to open the Variable dialog, then click From table:

   

2. In the dialog:
   1. Enter a Name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   2. Under CSV file, click the Select CSV file field to open the dialog:

      

      Select the CSV file from either the Current document, Other documents, or click the Import button at the bottom of the dialog to select a CSV file from your device.

      Once selected, click the file. It is loaded into the Select CSV file field.

   3. Fill out the Row and Column fields according to your requirements:
      • Access type - Select  By index, By index range, By label, or All values.
        • Index - If By index is selected, enter a single Index value.
        • Min/Max index - When By index range is selected, enter both the minimum and maximum index values.
        • Value - If By label is selected, enter the label's string value.
      • Regular expression - Check to pattern match a set of target strings.
      • Result type - Select Single value, Array, or Map.
        • Label column/row index - If the Result type is a Map, enter either a numerical index value or a variable.
   4. Check Conversion factor and enter a value with measurement units if you are converting from one measurement to another (for example, if the table uses inches, and you want these values converted to centimeters).

      

   5. Optionally, enter a Description to provide some details about the Variable or CSV file being used.
3. Click .

Examples

All examples below use the following 3x3 CSV table:

• An array of arrays - Setting Access type: All values and Result type: Array for both Row and Column creates an array of arrays that corresponds to the entire CSV file:

  

• Rows indexed by the first column - To index the CSV rows by the values in the first column, select Access type: All values, Result type: Map, and Label column index: 0 for Row. This sets the first column in the table as the map key.

  For Column, select Access type: By index range and set the Min/Max index range for the table columns (in the example below, a Min/Max index range of 1/2 is entered, which provides an array for the second and third columns in the table). Finally, select Result type: Array:

  

• First column - To access only the first column, set Access type: All values and Result type: Array for Row. Then select Access type: By index (0) and Result type: Single value for Column:

  

• First row - To access only the first row, set Access type: By index (0) and Result type: Single value for Row. Then select Access type: All values and Result type: Array for Column:

  

Notes

• To view the variable result, hover your mouse over the feature name. A tooltip displays the result from the CSV file:

  

• Since a variable is sourced from a table, its Variable type and Value in the Variable table are read-only (the Dimensions variable in the example below):

  

Create a dimension, in the dimension field enter # and the variable name (and optionally, as part of an expression, as shown below):

and

Save the dimension; the variable is replaced with the value and the expression (if applicable) is solved:

When you double-click the dimension for editing, the variable (and expression) is displayed:

If an expression without a variable is used for a sketch dimension, it is indicated with the Expression without a variable icon () to the left of the dimension value. If an expression with a variable is used for a sketch dimension, it is indicated with the Expression with variable icon () to the left of the dimension value. See Displaying expressions in a sketch.

Use variables anywhere you use expressions in a Part Studio. For example, in an extrude or revolve operation.

Start the operation as usual (in this case, Revolve); in the numeric value field, enter # and the variable name (or optionally, as part of an expression):

Accept the feature.

When you edit the feature, the solution is displayed in the numeric value field:

Click in the field and the variable (and expression, if applicable) is displayed.

Variable autofill feature

When you have defined variables, entering a hashtag (or pound sign, underscore, or any letter) in a numeric dialog field opens the variable autofill feature as shown below:

Left: using a variable in a dialog. Right: using a variable in a dimension field in a sketch.

You can keep typing to filter the list to reasonable options, use the arrow keys to move up and down in the list, and use the Enter key to accept a variable from the list when it is highlighted. You can also use the mouse scroll wheel to scroll the variable list and a mouse click to select a particular variable. Note that FeatureScript functions are also included in the list when the pound sign is not used:

Also note the following:

• Using the Escape key closes the dropdown without selecting anything. Removing focus from the dropdown also closes it without selecting anything.
• Compute values are shown in light gray, and will not be inserted (only the variable or function name is inserted). Likewise with function inputs, because the input placeholder names are not inserted.
• Only variables that exist in the current context are shown; variables further down in the Feature list are not shown

Variable values can contain expressions. You can specify an array with an index, and the index can be a variable. This allows you to change the value of the variable by changing the value of the index variable.

To use arrays in variables, you must first set up a zero-based index.

1. Create a variable and set the name to ‘config’. Select Number as the type, and set the value of #config to ‘2’.
2. Create a variable and set the name to ‘diameter’. Set the value of #diameter to ‘[0.25, 0.5, 1][#config]’.

It is the second set of brackets [#config] that serves as the index pointer in the array.

3. Create a variable and set the name to ‘length’. Set the value of #length to ‘[2, 4, 10][#config]’.

4. Create a circle.
5. Create a line.
6. Set the diameter of the circle to ‘#diameter’.

   Since #config = 2, the diameter of the circle is 1.

7. Set the length of the line to ‘#length’.

   Since #config = 2, the length of the line is 10.

Change the value of the index variable to change the indices of all array variables.

You can create variables as you need them, when entering a numeric value into a field in a feature dialog box, for example. The variable is saved preceding the current operation in the Feature list.

For example, when creating a sketch, when the dimension field pops up, instead of entering a value for the dimension, you can type the pound sign # and the list of existing variables is displayed, along with an option for a New variable:

Select New variable to open the Variable dialog to create a new variable and use it in the current field. (Otherwise, select one of the existing variables, if available.)

The Create variable dialog gives the option of creating a variable for a Feature (default) or a Configuration.

Enter a name for the new variable, as well as a value. Click the check mark to save the new variable and to use it in the open feature.

You can use FeatureScript functions in a variable, following the FeatureScript syntax.

For example, you might create a variable of type Any, named “Adjust”, to store a function that doubles a given length and adds 2.5mm, as follows:

function(len) { return len * 2 + 2.5 mm; }

and then reference that variable in an expression, such as:

#Adjust(20mm)

• When you change the value of a variable (edit it as you would any feature), all operations that use the variable are automatically updated.
• When you change the name of a variable, you have the choice to propagate the change everywhere the variable is used:

  

  Check the box next to Update all references.

1. While in a Part Studio, select the Variable tool icon () to open the Variable tool dialog box:

   

2. In the dialog box:
   1. Select a type:
   • Length - A numeric value representing a length (decimal, integer, fraction)
   • Angle - A numeric value representing an angle (decimal, integer, fraction)
   • Number - A numeric value (decimal, integer, fraction)
   • Any - Any of the above, a numeric value with different units, or a FeatureScript value such as boolean, map, array, string, or a function. See https://cad.onshape.com/FsDoc/variables.html#standard-types and examples below.
   2. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   3. Enter a value (and optionally, units for Length, Angle, and Any).
3. Tap the checkmark.

The variable you created is listed in the Feature List and displays the name and value of the variable.

1. While in a Part Studio, select the Variable tool icon () to open the Variable tool dialog box, then tap Measured:

   

2. In the dialog:
   1. Select a type:
   • Distance - A numeric value representing a distance (decimal, integer, fraction)
   • Length - A numeric value representing a length (decimal, integer, fraction)
   • Diameter - A numeric value representing an angle (decimal, integer, fraction)

3. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   1. Select entities to measure between.
   2. Fill out the remaining fields according to your preferences.
4. Tap the checkmark.

The variable you created is listed in the Feature List and displays the name and value of the variable.

The From table option in the Variable feature enables users to create a single variable that stores a subset of rows and columns from the CSV table. The Row options filter the rows and determine the Result type (Single value, Array, or Map) of the variable. The Column options then filter each row and determine the type of each entry in the final variable.

iOS support for creating a Variable from a CSV file (From table) is limited to editing and viewing variables created on the desktop (browser) platform.

1. Tap to open the Variable dialog, then tap From table:

   

2. In the dialog:
   1. Enter a Name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   2. Under CSV file, tap the Select CSV file field to select and open an existing CSV file. It is loaded into the Select CSV file field.

      Fill out the Row and Column fields according to your requirements:

      • Access type - Select  By index, By index range, By label, or All values.
        • Index - If By index is selected, enter a single Index value.
        • Min/Max index - When By index range is selected, enter both the minimum and maximum index values.
        • Value - If By label is selected, enter the label's string value.
      • Regular expression - Check to pattern match a set of target strings.
      • Result type - Select Single value, Array, or Map.
        • Label column/row index - If the Result type is a Map, enter either a numerical index value or a variable.
   3. Toggle Conversion factor and enter a value with measurement units if you are converting from one measurement to another (for example, if the table uses inches, and you want these values converted to centimeters).
   4. Optionally, enter a Description to provide some details about the Variable or CSV file being used.
3. Tap the checkmark.

Create a dimension, in the dimension field enter # and the variable name (and optionally, as part of an expression, as shown below):

and

Save the dimension; the variable is replaced with the value and the expression (if applicable) is solved:

When you double-click the dimension for editing, the variable (and expression) is displayed:

Use variables anywhere you use expressions in a Part Studio. For example, in an extrude or revolve operation:

Start the operation as usual (in this case, Revolve); in the numeric value field, enter # and the variable name (or optionally, as part of an expression). For example: (#x) deg.

Accept the feature.

When you edit the feature, the solution is displayed in the numeric value field. For example: 4 deg.

Click in the field and the variable (and expression, if applicable) is displayed.

Variable values can contain expressions but must evaluate to a scalar value. You can specify an array with an index, and the index can be a variable. This allows you to change the value of the variable by changing the value of the index variable.

To use arrays in variables you must first set up a zero-based index.

1. Tap the Variable tool and set the name to "config." Set the value of #config to 2.
2. Tap the Variable tool and set the name to "diameter." Set the value of #diameter to [0.25, 0.5, 1] [#config].

It is important that you include the second set of brackets that contain "#config." This is what allows the value of the variable #config to point to the correct place in the array.

3. Tap the Variable tool and set the name to "length." Set the value of #length to [2, 4, 10] [#config].

It is important that you include the second set of brackets that contain "#config." This is what allows the value of the variable #config to point to the correct place in the array.

4. Tap the sketch tool and sketch a circle.
5. Tap the sketch tool and sketch a line.
6. Set the diameter of the circle to "#diameter".
7. Set the length of the line to "#length".

   The diameter of the circle is set to 1, and the length of the line is set to 10.

8. Edit the #config variable, set the value to 0.

The sketch updates and the circle diameter is now set to 0.25 and the line length is set to 2.

You can do this for as many arrays as you like, and your arrays can hold infinite places (they are not limited to only three values as this example shows).

You can use FeatureScript functions in a variable, following the FeatureScript syntax.

For example, you might create a variable of type Any, named “Adjust”, to store a function that doubles a given length and adds 2.5mm, as follows:

function(len) { return len * 2 + 2.5 mm; }

and then reference that variable in an expression, such as:

#Adjust(20mm)

• When you change the value of a variable (edit it as you would any feature), all operations that use the variable are automatically updated.
• Variable names are case-sensitive.
• You can input a variable as a stand-alone value or as part of an equation.
• You can use a variable in a dimension, expression, or feature.

• In cases where you specify a variable without a unit, expressions will also be unitless or assume the unit of the workspace. But if you explicitly add units to a variable value, then any expression should also match that unit when being written in order to be valid.

• When you change the name of a variable, you have the choice to propagate the change everywhere the variable is used:

  

  Select Update all references.

1. While in a Part Studio, select the Variable tool to open the Variable tool dialog box:

   

2. In the dialog box:
   1. Select a type:
   • Length - A numeric value representing a length (decimal, integer, fraction)
   • Angle - A numeric value representing an angle (decimal, integer, fraction)
   • Number - A numeric value (decimal, integer, fraction)
   • Any - Any of the above, a numeric value with different units, or a FeatureScript value such as boolean, map, array, string, or a function. See https://cad.onshape.com/FsDoc/variables.html#standard-types and examples below.
   2. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   3. Enter a value (and optionally, units for Length, Angle, and Any).
3. Tap the checkmark.

The variable you created is listed in the Feature List and displays the name and value of the variable.

1. While in a Part Studio, select the Variable tool to open the Variable tool dialog box, then click Measured:

   

2. In the dialog:
   1. Select a type:
   • Distance - A numeric value representing a distance (decimal, integer, fraction)
   • Length - A numeric value representing a length (decimal, integer, fraction)
   • Diameter - A numeric value representing an angle (decimal, integer, fraction)

3. Enter a name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   1. Select entities to measure between.
   2. Fill out the remaining fields according to your preferences.
4. Tap the checkmark.

The variable you created is listed in the Feature List and displays the name and value of the variable.

The From table option in the Variable feature enables users to create a single variable that stores a subset of rows and columns from the CSV table. The Row options filter the rows and determine the Result type (Single value, Array, or Map) of the variable. The Column options then filter each row and determine the type of each entry in the final variable.

Android support for creating a Variable from a CSV file (From table) is limited to editing and viewing variables created on the desktop (browser) platform.

1. Tap to open the Variable dialog, then tap From table:

   

2. In the dialog:
   1. Enter a Name for the variable (and by which to reference it).

   Use only English alphanumeric characters and underscores (_) in the Name field. Variable names are case-sensitive and cannot start with a number.

   2. Under CSV file, tap the Select CSV file field to select and open an existing CSV file. It is loaded into the Select CSV file field.

      Fill out the Row and Column fields according to your requirements:

      • Access type - Select  By index, By index range, By label, or All values.
        • Index - If By index is selected, enter a single Index value.
        • Min/Max index - When By index range is selected, enter both the minimum and maximum index values.
        • Value - If By label is selected, enter the label's string value.
      • Regular expression - Check to pattern match a set of target strings.
      • Result type - Select Single value, Array, or Map.
        • Label column/row index - If the Result type is a Map, enter either a numerical index value or a variable.
   3. Toggle Conversion factor and enter a value with measurement units if you are converting from one measurement to another (for example, if the table uses inches, and you want these values converted to centimeters).
   4. Optionally, enter a Description to provide some details about the Variable or CSV file being used.
3. Tap the checkmark.

Create a dimension, in the dimension field enter # and the variable name (and optionally, as part of an expression, as shown below):

and

Save the dimension; the variable is replaced with the value and the expression (if applicable) is solved:

When you double-click the dimension for editing, the variable (and expression) is displayed:

Use variables anywhere you use expressions in a Part Studio. For example, in an extrude or revolve operation:

Start the operation as usual (in this case, Revolve); in the numeric value field, enter # and the variable name (or optionally, as part of an expression). For example: (#x) deg.

Accept the feature.

When you edit the feature, the solution is displayed in the numeric value field. For example: 4 deg.

Click in the field and the variable (and expression, if applicable) is displayed.

Variable values can contain expressions but must evaluate to a scalar value. You can specify an array with an index, and the index may be a variable. This allows you to change the value of the variable by changing the value of the index variable.

To use arrays in variables you must first set up a zero-based index.

1. Tap the Variable tool and set the name to "config." Set the value of #config to 2.
2. Tap the Variable tool and set the name to "diameter." Set the value of #diameter to [0.25, 0.5, 1] [#config].

It is important that you include the second set of brackets that contain "#config." This is what allows the value of the variable #config to point to the correct place in the array.

3. Tap the Variable tool and set the name to "length." Set the value of #length to [2, 4, 10] [#config].

It is important that you include the second set of brackets that contain "#config." This is what allows the value of the variable #config to point to the correct place in the array.

4. Tap the sketch tool and sketch a circle.
5. Tap the sketch tool and sketch a line.
6. Set the diameter of the circle to "#diameter".
7. Set the length of the line to "#length".

   The diameter of the circle is set to 1, and the length of the line is set to 10.

8. Edit the #config variable, set the value to 0.

The sketch updates and the circle diameter is now set to 0.25 and the line length is set to 2.

You can do this for as many arrays as you like, and your arrays are able to hold infinite places (they are not limited to only three values as this example shows).

You can use FeatureScript functions in a variable, following the FeatureScript syntax.

For example, you might create a variable of type Any, named “Adjust”, to store a function that doubles a given length and adds 2.5mm, as follows:

function(len) { return len * 2 + 2.5 mm; }

and then reference that variable in an expression, such as:

#Adjust(20mm)

• When you change the value of a variable (edit it as you would any feature), all operations that use the variable are automatically updated.
• Variable names are case-sensitive.
• You can input a variable as a stand-alone value or as part of an equation.
• You can use a variable in a dimension, expression, or feature.