Introduction #

SmartChart’s parameter mechanism is the core of chart linkage, filters, and data permissions. By embedding “magic comment” syntax in SQL, you can dynamically control query conditions without modifying SQL structure.

Use Cases #

• Chart linkage effects
• Data service API development
• Row-level data permission control

Magic Syntax Quick Reference #

Basic Principles #

1. $param_name: Replaces value when parameter is passed
2. /* ... $param_name ... */: Code block is ignored when no parameter, opened when parameter exists
3. --: Ignores single line of code after this marker

Common Combinations #

• Basic usage:

select xx from table_name where calmonth = '$month'

• Default parameter: Default to current month when no parameter passed:

select xx from tablename where
calmonth =/*'$calmonth' -- */ to_char(sysdate,'YYYYMM')

• Multiple parameters: Note 1=1 and and positioning:

select xx from tablename where 1=1
/* and city = '$city' */
/* and calmonth ='$calmonth'*/

• No query when no parameter:

select xx from tablename where 1=1
/* and city = '$city' */
/* and calmonth ='$calmonth'*/
/* -- $city $calmonth */ and 1=0

• Dimension change: Use field as parameter:

select /*$calmonth,*/ city, count(1) as qty from tablename
group by /*$calmonth,*/ city

Advanced Switch #

Use $param__value as a switch:

/* select count(1) as qty from tablename1  -- $type__1*/
/* select count(1) as qty from tablename2  -- $type__2*/

Debug Parameters #

Method 1: Use “Tools” → “Parameter Debug” menu.

Method 2: Write default parameters in SQL editor:

/* {"month":"202009","city":"Zhongshan"} */
select xxx from table xxx

Data Permission Row-Level Control #

• $username auto-replaces with logged-in user
• Use URL parameter $_id for embedded third-party systems

select * from sales_data
where 1=1
/* and region = (select region from user_region where username = '$username') */

Parameter Passing #

• From URL: &param={"param_name":"param_value"}
• Through chart linkage click events (see linkage docs)

When parameters are set, dataset caching is disabled. Parameters cannot contain # character.