File Output Policy
GSQL restricts where a query can produce output to files through a file output policy. The policy consists of a whitelist and a blacklist.
  • GSQL queries must only output to the directories and their descendants or the files indicated by paths in the whitelist.
  • GSQL queries cannot output to the directories and their descendants or the files indicated by paths in the blacklist. The blacklist takes precedence over the whitelist.
By default, the file output policy allows outputs to all files.

GSQL.FileOutputPolicy

The file output policy is implemented through the system configuration parameterGSQL.FileOutputPolicy, which is a JSON array of strings that represents a list of paths. If there is an exclamation mark (!) preceding a path, the path is on the blacklist. If there is no exclamation mark preceding a path, the path is on the whitelist.

Example

For example, if the value for GSQL.FileOutputPolicy is ["/home/tigergraph", "!/home/tigergraph/documents", "!/home/tigergraph/desktop"], then below are the paths on the white list and on the black list:
  • Whitelist: /home/tigergraph and all its descendants
  • Blacklist: /home/tigergraph/documents, /home/tigergraph/desktop and all their descendants.
Since the blacklist takes precedence, GSQL will allow queries to write to all files and directories under /home/tigergraph except the documents and destktop folders.

Edit the file output policy

  1. 1.
    To edit the file policy, ensure that you are logged in as the TigerGraph Linux user, and run the following command:
    1
    $ gadmin config entry GSQL.FileOutputPolicy
    Copied!
  2. 2.
    In the prompt, enter the new value for the parameter:
    1
    GSQL.FileOutputPolicy [ ["/"] ]: The policy to control file outputs in GSQL queries
    2
    New: ["/home/tigergraph", "!/home/tigergraph/app"]
    3
    # Whitelist: /home/tigergraph and all its descendants
    4
    # Blacklist: /home/tigergraph/app and all its decendants
    5
    # Effect: GSQL can output to /home/tigergraph and all its decendants except /home/tigergraph/app
    Copied!
  3. 3.
    Apply the new configurations and restart GSQL
    1
    $ gadmin config apply
    2
    $ gadmin restart gsql
    Copied!
After implementing the file output policy, queries that write to paths that are not on the whitelist are forbidden:
1
GSQL > BEGIN
2
GSQL > CREATE QUERY fileOutput() FOR GRAPH tpc_graph {
3
GSQL > FILE f ("/home/documents/data.txt");
4
GSQL > }
5
GSQL > END
6
7
Semantic Check Error in query fileOutput (SEM-2502): line 2, col 7
8
The path '/home/documents/data.txt' is not allowed by the file output policy.
9
For more info, please check log at node 'm2': /home/tigergraph/tigergraph/log/gsql/log.ERROR
10
Failed to create queries: [fileOutput].
11
Copied!
If a FILE object is defined with an empty string, it is regarded as a null file. The file output policy will not block the definition of the FILE object, but writing to a null file would cause a runtime error.
Additionally, queries that write to paths on the whitelist, but also on the blacklist are also forbidden:
1
GSQL > BEGIN
2
GSQL > CREATE QUERY fileOutput() FOR GRAPH tpc_graph {
3
GSQL > FILE f ("/home/tigergraph/app/data.txt");
4
GSQL > }
5
GSQL > END
6
7
Semantic Check Error in query fileOutput (SEM-2502): line 3, col 7
8
The path '/home/tigergraph/app/data.txt' is not allowed by the file output
9
policy.
10
For more info, please check log at node 'm2': /home/tigergraph/tigergraph/log/gsql/log.ERROR
11
Failed to create queries: [fileOutput].
Copied!
Last modified 1mo ago