# 配置清单

| Property Name                               | Default | Meaning                                                      |
| ------------------------------------------- | ------- | ------------------------------------------------------------ |
| spark.xsql.properties.file | xsql.conf | 用于指定包含所有XSQL配置的属性文件。单独的XSQL属性文件便于对XSQL配置信息进行运维、管理。如果不指定此属性，用户需要将XSQL参数配置到spark-default.conf或者通过--conf传递。 |
| spark.xsql.datasources                      | None    | 用于指定用户使用的数据源。数据源可以有多个，之间使用英文逗号分隔，例如：default,customer,order。 |
| spark.xsql.default.datasource               | default | 用于指定XSQL默认的数据源。                                   |
| spark.xsql.default.database                 | default | 用于指定XSQL在默认数据源中默认使用的数据库。                 |
| spark.xsql.datasource.$dataSource.type      | None    | 用于指定数据源的类型，例如：mysql。                          |
| spark.xsql.datasource.$dataSource.url       | None    | 用于指定数据源的url地址，不同数据源的Url格式不同，请分别查看各数据源Configuration配置。 |
| spark.xsql.datasource.$dataSource.user      | None    | 用于指定数据源账号的用户名。                                 |
| spark.xsql.datasource.$dataSource.password  | None    | 用于指定数据源账号的密码。                                   |
| spark.xsql.datasource.$dataSource.version   | None    | 用于指定数据源的版本，例如MySQL的版本有5.6.19。              |
| spark.xsql.datasource.$dataSource.whitelist | None    | 用于指定数据源的Database及Table白名单。由于一些数据源中有大量的Database及Table，所以会导致启动XSQL时花费大量的时间。另一方面，每个用户只对其中的少数Database及Table感兴趣，因此可以提供白名单加速XSQL的启动。 |
| spark.xsql.datasource.$dataSource.pushdown  | true    | 用于控制指定数据源的查询是否优先采用下推方式。此配置将建议XSQL对此数据源的查询使用下推方式，但是并不能保证。很多情况下，XSQL并不会下推，例如：数据源查询还包含有其他数据源的子查询，或者引用了外部查询的别名。 |
| spark.xsql.datasource.$dataSource.schemas   | None    | 用于定义数据源中表的Schema信息。只适用于无严格Schema的数据源，例如：Redis、HBASE、MongoDB |
| spark.xsql.datasource.$dataSource.schemas.discover | false | 对于无严格Schema的数据源，使用spark.xsql.datasource.$dataSource.schemas指定Schema配置文件，对于用户不太友好，而且一些复杂数据类型的定义（例如：ElasticSearch的nested类型）也十分繁琐。XSQL提供了对schema信息进行探索的能力，用户可以打开此开关，启用schema探索。注意：目前，此配置只对ElasticSearch和MongoDB有效。 |
| spark.xsql.datasource.$dataSource.cache.level | 1     | 用于指定数据源的元数据缓存级别，1表示Level One，2表示Level Two。 |
| spark.xsql.datasource.$dataSource.cluster   | None    | 用于定义数据源优先采用的Yarn集群。如果用户首次提交非下推的任务，那么此任务将会被提交到对应的Yarn集群。如果未指定此配置，对于Hive将选择Hive元数据服务所在的集群，其他数据源则仍然选择$XSQL_HOME/hadoopconf/yarn-site.xml文件所配置的Yarn集群。 |
| spark.xsql.yarn.$clusterName                | None    | 用于指定用户使用的Yarn集群的名称及相关配置文件。             |

## 配置数据源库表白名单

​	白名单是通过json格式的配置文件进行配置的，为便于用户理解，我们指定default数据源的白名单配置文件为hive-whitelist.conf：

```properties
spark.xsql.datasource.default.whitelist        hive-whitelist.conf
```

这里给出一个简单的hive-whitelist.conf的配置内容：

```json
{
  "default": {
    "includes": [
      "tableA",
      "tableB",
      "tableC",
      "tableD",
      "tableE",
      "tableF"
    ],
    "excludes": ["tableD"]
  }
}
```

default是数据库名称。数据库级别只有白名单，而没有黑名单，也就是说XSQL中只有在白名单中明确配置的数据库才是可见的。每个数据库都可以配置includes和excludes两个属性，分别表示白名单和黑名单。在白名单中包括了table[A-F]共6张表，同时黑名单中包括了tableD一张表。在XSQL中黑名单拥有最高的优先级，将会从白名单中清楚表，因此在XSQL中只有table[A-D]、tableE、tableF共5张表可见。表默认是属于白名单的，所以当用户需要数据库中的所有表都可见时，可以不配置includes。

## 配置NoSQL数据源的Schema文件

​	有些类型的数据源没有明确、严格的Schema定义，XSQL无法通过访问数据源得到各个表的Schema信息。为了能够接入XSQL，需要用户手动配置数据源的Schema信息。配置采用了json格式，就像下面的例子一样：

```json
{
	"database_A": [{
			"table": "table_A_1",
			"fields": [{
					"name": "_id",
					"type": "object_Id",
					"hidden": false
				}, {
					"name": "item",
					"type": "string",
					"hidden": false
				},
				{
					"name": "qty",
					"type": "int",
					"hidden": false
				},
				{
					"name": "tags",
					"type": "array<string>",
					"hidden": false
				},
				{
					"name": "dim_cm",
					"type": "array<int>",
					"hidden": false
				}
			]
		},
		{
			"table": "table_A_2",
			"fields": [{
					"name": "id",
					"type": "long",
					"hidden": false
				},
				{
					"name": "name",
					"type": "string",
					"hidden": false
				},
				{
					"name": "is_man",
					"type": "boolean",
					"hidden": false
				},
				{
					"name": "age",
					"type": "int",
					"hidden": false
				},
				{
					"name": "salary",
					"type": "double",
					"hidden": false
				},
				{
					"name": "format_salary",
					"type": "decimal(12,2)",
					"hidden": false
				},
				{
					"name": "graduation_time",
					"type": "date",
					"hidden": false
				},
				{
					"name": "birthday",
					"type": "string",
					"hidden": false
				},
				{
					"name": "score",
					"type": "decimal(5,1)",
					"hidden": false
				}
			]
		}
	],
	"database_B": [{
		"table": "table_B_1",
		"fields": [{
				"name": "_id",
				"type": "object_Id",
				"hidden": false
			}, {
				"name": "VendorID",
				"type": "int",
				"hidden": false
			},
			{
				"name": "pickup_datetime",
				"type": "string",
				"hidden": false
			},
			{
				"name": "total_amount",
				"type": "double",
				"hidden": false
			}
		]
	}]
}
```

此处以MongoDB的Schema为例。其他数据源主要是字段允许的类型不同。

## 选择运行集群

有时候，用户的数据源位于不同的集群环境中。为了使得Yarn分配的资源与数据之间更加接近，可以为数据源显示指定Yarn集群。spark.xsql.yarn.$clusterName属性中的clusterName是用户给Yarn集群起的别名，对应的值必须是一个有效的属性配置文件。

例如，我们定义了一个名为yarn-cluster0的Yarn集群，并指定了对应的配置文件为

```properties
spark.xsql.yarn.cluster0  yarn-cluster0.conf
```

yarn-cluster0.conf文件中的配置信息可能为：

```properties
spark.yarn.stagingDir    hdfs://namenode.dfs.cluster0.yahoo.com:9000/home/spark/cache
spark.hadoop.yarn.resourcemanager.cluster-id  cluster0-yarn
spark.hadoop.yarn.resourcemanager.zk-state-store.address  m3.dfs.cluster0.yahoo.com:2181,m4.dfs.cluster0.yahoo.com:2181,m5.dfs.cluster0.yahoo.com:2181,m6.dfs.cluster0.yahoo.com:2181
spark.hadoop.yarn.resourcemanager.zk-address  m2.dfs.cluster0.yahoo.com:2181,m3.dfs.cluster0.yahoo.com:2181,m4.dfs.cluster0.yahoo.com:2181,m5.dfs.cluster0.yahoo.com:2181,m6.dfs.cluster0.yahoo.com:2181
spark.hadoop.yarn.resourcemanager.zk-state-store.parent-path  /cluster0/yarn/rmstore
spark.hadoop.yarn.resourcemanager.hostname.rm1  m7.dfs.cluster0.yahoo.com
spark.hadoop.yarn.resourcemanager.hostname.rm2  m8.dfs.cluster0.yahoo.com
spark.hadoop.yarn.resourcemanager.scheduler.address.rm1  m7.dfs.cluster0.yahoo.com:8830
spark.hadoop.yarn.resourcemanager.resource-tracker.address.rm1  m7.dfs.cluster0.yahoo.com:8831
spark.hadoop.yarn.resourcemanager.address.rm1  m7.dfs.cluster0.yahoo.com:8832
spark.hadoop.yarn.resourcemanager.admin.address.rm1  m7.dfs.cluster0.yahoo.com:8833
spark.hadoop.yarn.resourcemanager.webapp.address.rm1  m7.dfs.cluster0.yahoo.com:8888
spark.hadoop.yarn.resourcemanager.ha.admin.address.rm1  m7.dfs.cluster0.yahoo.com:23142
spark.hadoop.yarn.resourcemanager.scheduler.address.rm2  m8.dfs.cluster0.yahoo.com:8830
spark.hadoop.yarn.resourcemanager.resource-tracker.address.rm2  m8.dfs.cluster0.yahoo.com:8831
spark.hadoop.yarn.resourcemanager.address.rm2  m8.dfs.cluster0.yahoo.com:8832
spark.hadoop.yarn.resourcemanager.admin.address.rm2  m8.dfs.cluster0.yahoo.com:8833
spark.hadoop.yarn.resourcemanager.webapp.address.rm2  m8.dfs.cluster0.yahoo.com:8888
spark.hadoop.yarn.resourcemanager.ha.admin.address.rm2  m8.dfs.cluster0.yahoo.com:23142
spark.hadoop.yarn.log.server.url  http://m8.dfs.cluster0.yahoo.com:19888/jobhistory/logs
```

## 下推执行时的条数限制

当对数据源的查询实际采用了下推方式时，XSQL将在用户未指定limit时，默认会加上limit 10的限制。这样做得目的有两点：

首先，Pushdown实际运行在Driver进程中，Driver的内存往往是有限的。如果不加以限制，将数GB甚至更多的数据读取到Driver，将会引发XSQL的内存问题，譬如：GC频繁、OOM。

其次，对于某些数据源，如果没有显式的limit限制，数据源本身也有限制（例如Elasticsearch会加上limit 10的限制）。

如果用户需要更多的返回数据，请显式增加limit语句。目前XSQL能够接受的limit的最大值是10000。

## 使用私有的xsql.conf

为了防止用户的数据源连接帐号密码泄露，XSQL提供了使用私有xsql.conf的配置方法：

```properties
spark.xsql.properties.file customer_name.conf
spark.xsql.conf.dir /home/username/xxx/xx
```

与之配合的在目录/home/username/xxx/xx下创建customer_name.conf，写入适当的数据源连接信息。此类配置不建议修改在spark-defaults.conf配置文件中，完整的提交命令如下：

```shell
/usr/bin/hadoop/software/spark-xsql/bin/spark-xsql --conf spark.xsql.properties.file=customer_name.conf --conf spark.xsql.conf.dir=/home/username/xxx/xx
```

## 使用字符串变量拼接SQL查询

对于一些定时任务，查询语句中需要传入随时间变化的查询变量，XSQL同样提供了这样的功能，首先看下面的示例提交命令：

```
/usr/bin/hadoop/software/spark-xsql/bin/spark-xsql --conf spark.key=value
```

那么，在之后的查询语句可以以下表达式：

```sql
select '${spark.key}' as date from example_table;
```

注意，${}符号必须被单引号或双引号所包裹，不能够独立存在，否则会语法解析报错。由于SparkConf要求所有的配置项必须以`spark.`开头，因此\${}内的查询变量也必须以`spark.`开头。

## 开启HBase或Druid数据源

为了控制XSQL依赖jar包的数量，XSQL默认不开启依赖较多的HBase模块和Druid模块，当需要使用这些模块时，可以添加以下配置：

```properties
spark.driver.extraClassPath  /usr/bin/hadoop/software/spark-xsql/hbase/*:/usr/bin/hadoop/software/spark-xsql/druid/*
spark.xsql.extraDatasourceManagers org.apache.spark.sql.xsql.manager.HBaseManager,org.apache.spark.sql.xsql.manager.DruidManager
```

## 开启hive权限控制

对于XSQL带权限控制的部署版本，要想开启权限控制，还需要添加额外的配置：

```
spark.sql.extensions org.apache.ranger.authorization.spark.authorizer.RangerSparkSQLExtension
```

hive-site.mxl也需要添加如下配置：

```xml
<property>
    <name>hive.security.authorization.enabled</name>
        <value>false</value>
        </property>
<property>
    <name>hive.security.authorization.manager</name
     <value>org.apache.hadoop.hive.ql.security.authorization.plugin.sqlstd.SQLStdHiveAuthorizerFactory</value>
   </property>
<property>
    <name>hive.security.authenticator.manager</name>
        <value>org.apache.hadoop.hive.ql.security.SessionStateUserAuthenticator</value>
        </property>
<property>
    <name>hive.conf.restricted.list</name>
 <value>hive.security.authorization.enabled,hive.security.authorization.manager,hive.security.authenticator.manager</value>
        </property>
```

## 开启自适应执行

对于XSQL带自适应执行的部署版本，要想开启自适应执行，还需要添加额外的配置：

```
spark.sql.adaptive.enabled true
spark.sql.adaptive.shuffle.targetPostShuffleInputSize 134217728
spark.sql.adaptive.join.enabled true
spark.sql.adaptive.skewedJoin.enabled true
spark.sql.adaptive.skewedPartitionFactor 5
spark.sql.adaptive.skewedPartitionSizeThreshold 134217728
spark.sql.adaptive.skewedPartitionRowCountThreshold 20000000
spark.shuffle.statistics.verbose true

spark.shuffle.service.enabled  false
spark.dynamicAllocation.enabled   false
spark.executor.instances     150
```

