配置清单

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:

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

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

{
  "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格式,就像下面的例子一样:

{
    "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集群,并指定了对应的配置文件为

spark.xsql.yarn.cluster0  yarn-cluster0.conf

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

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  m2.dfs.cluster0.qihoo.net: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-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的配置方法:

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配置文件中,完整的提交命令如下:

/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

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

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

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

开启HBase或Druid数据源

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

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也需要添加如下配置:

<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