文档中心

搜索

全部文档

开发者中心

文档中心开发者中心 Python SDK维度

维度

本文档说明维度组件对外开放的常用接口，适用于外部系统查询维度成员、按表达式取数，以及通过接口进行维度成员维护。

如需通过 Python 接入维度能力，可使用 deepfos SDK。更多说明可参考：

https://py.deepfos.com/quick_start/element_dimension.html

1. 初始化维度对象

Copy

from deepfos.element.dimension import Dimension, DimMember

# 连接已有维度
org_dim = Dimension("org")

2. 新增成员

Copy

from deepfos.element.dimension import Dimension, DimMember

org_dim = Dimension("org")

org_dim.add_member(
    DimMember(
        name="A01",
        parent_name="A",
        description="华北区组织"
    )
).save()

3. 删除成员

Copy

from deepfos.element.dimension import Dimension

org_dim = Dimension("org")
org_dim.delete_member("A02").save()

4. 查询成员

基础查询

Copy

from deepfos.element.dimension import Dimension

org_dim = Dimension("org")
member_names = [m.name for m in org_dim.members]
print(member_names)

使用表达式查询

更常见的用法是通过 query() 方法配合维度表达式查询成员。

Copy

from deepfos.element.dimension import Dimension
import pandas as pd

# 查询整棵维度树
dim = Dimension("Account")
df_members = pd.DataFrame(
    dim.query(
        "IDescendant(#root,0)",
        as_model=False,
        fields=["name", "parent_name", "multilingual"]
    ),
    columns=["name", "parent_name", "multilingual"]
)

# 提取中英文名称
df_members["name_cn"] = df_members["multilingual"].apply(lambda x: x.get("zh-cn"))
df_members["name_en"] = df_members["multilingual"].apply(lambda x: x.get("en"))

查询成员属性字段

Copy

from deepfos.element.dimension import Dimension
import pandas as pd

# 查询场景维度的 start_period 属性
# 适合将维度作为配置表使用
scenario_dim = Dimension("Scenario")
df_scenarios = pd.DataFrame(
    scenario_dim.query("F06", as_model=False, fields=["name", "start_period"]),
    columns=["name", "start_period"]
)
start_period = df_scenarios["start_period"][0]

# 查询业务维度的自定义属性字段
# 适合根据成员属性建立业务映射关系
project_dim = Dimension("A_HotelProject")
df_projects = pd.DataFrame(
    project_dim.query("Base(HP0198,0)", as_model=False, fields=["name", "ud1"]),
    columns=["name", "ud1"]
)

常用表达式

Copy

# 查询基础成员
"Base(TENTITY,0)"

# 查询所有后代
"IDescendant(#root,0)"

# 查询直接子节点
"Children(TENTITY,0)"

# 按成员属性进行过滤
"NAndFilter(IDescendant(E0101,0),Attr(ud14,'Y'))"

# 组合表达式
"Base(A03,0);Remove(Base(A04,0),Base(A01,0))"

5. DataFrame 批量保存

适合外部主数据批量同步场景。

Copy

import pandas as pd
from deepfos.element.dimension import Dimension

org_dim = Dimension("org")

df = pd.DataFrame([
    {
        "name": "A",
        "parentName": "#root",
        "description": "中国区域"
    },
    {
        "name": "A01",
        "parentName": "A",
        "description": "华东区组织"
    },
    {
        "name": "A02",
        "parentName": "A",
        "description": "华南区组织"
    }
])

org_dim.load_dataframe(df, strategy="full_replace")

6. SDK 与接口关系

维度能力既可通过 HTTP 接口集成，也可通过 Python SDK 调用。对外对接时，可根据集成方式选择其一。

表达式查询能力可通过 /dimension/query/select-dimension-member-by-name-function 调用，也可在 Python 中使用 Dimension(...).query(...)
增量维护能力可通过 /dimension-save/dimension-member-change-save 调用，也可在 Python 中使用 add_member(...).save()、delete_member(...).save() 等方式
批量保存能力可通过 /dimension/member/save-dimension-member 调用，也可在 Python 中使用 load_dataframe(..., strategy="full_replace")

如使用 Python 集成，建议优先采用 SDK 封装能力；如需与其他语言或外部系统集成，可直接使用本文列出的公开 HTTP 接口。

常见示例

示例 1：读取维度成员并转为 DataFrame

通过 query() 配合维度表达式，可以按需获取成员范围及其属性。

Copy

from deepfos.element import Dimension
import pandas as pd

dim = Dimension('Entity', path='/Application/01_CNHotel/01_DIM/')
df_entity = pd.DataFrame(
    dim.query('IDescendant(#root,0)', fields=['name', 'parent_name'], as_model=False)
)

适用场景：

读取基础成员清单
获取 parent_name、is_base、ud* 等属性后做映射
给后续 Cube/DataTable 处理准备维度范围

示例 2：读取基础成员/Base 成员

当只需要获取叶子成员时，可直接使用 Base(...) 表达式查询。

Copy

from deepfos.element import Dimension
import pandas as pd

brand_dim = Dimension('Brand')
brand_df = pd.DataFrame(
    brand_dim.query('Base(#root,0)', as_model=False, fields=['name']),
    columns=['name']
)

适用场景：

取叶子成员
构造筛选范围
生成下游查询或写回的 POV

示例 3：读取带属性过滤的成员

当需要根据成员属性缩小查询范围时，可将表达式与属性过滤条件组合使用。

Copy

from deepfos.element import Dimension
import pandas as pd

entity_dim = Dimension('Z_ENTITY')
entity_df = pd.DataFrame(
    [[i.name, i.parent_name, i.is_base]
     for i in entity_dim.query(
         'AndFilter(Descendant(#root,0),Attr(sharedmember,0))',
         ['name', 'parent_name', 'is_base']
     )],
    columns=['name', 'parent_name', 'is_base']
)

适用场景：

只取满足属性条件的成员
排除共享成员
给分摊、合并、校验脚本准备目标范围

示例 4：读取场景属性并参与业务判断

维度成员属性也可以作为业务参数使用，例如读取场景的开始期间。

Copy

from deepfos.element import Dimension
import pandas as pd

df_scenario = pd.DataFrame(
    Dimension('Scenario').query(
        'Remove(IDescendant(Final,0),F00)',
        ['name', 'start_period'],
        False
    )
)

适用场景：

读取场景开始期间
根据场景属性决定版本复制或汇率计算逻辑

示例 5：通过 `load_dataframe()` 维护维度数据

当需要批量同步维度成员时，可先准备 DataFrame，再通过 load_dataframe() 统一装载。

Copy

from deepfos.element import Dimension

Dimension(element_name='M2', path='/Application/01_CNHotel/01_DIM/').load_dataframe(
    dataframe=df_MEntity,
    is_base=True
)

适用场景：

批量导入维度成员
从外部表同步维度树

使用说明

维度查询场景中，通常优先使用 query() 配合表达式获取成员范围。
若需要读取业务配置，可直接返回 parent_name、is_base、ud*、start_period 等属性字段。
若需要批量维护维度成员，可使用 add_member(...).save()、delete_member(...).save() 或 load_dataframe(...)。
Base(...)、IDescendant(...)、Children(...)、Attr(...) 是最常见的表达式写法。