deepfos 1.1.60__py3-none-any.whl → 1.1.78__py3-none-any.whl

deepfos/element/deepmodel.py

@@ -1,4 +1,6 @@
 import re
+import textwrap
+import threading
 
 import numpy as np
 from asyncpg.connection import connect as pg_conn
@@ -6,7 +8,7 @@ import json
 import uuid
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
-from itertools import count
+from itertools import count, chain
 from typing import (
     List, TYPE_CHECKING, Any, Dict, Union, NamedTuple,
     Iterable, Optional, Literal
@@ -15,9 +17,10 @@ from typing import (
 import edgedb
 import pandas as pd
 from loguru import logger
-from pydantic import BaseModel, parse_obj_as, ValidationError, Field
+from pydantic import BaseModel, ValidationError, Field
 
 from deepfos import OPTION
+from deepfos.api.models import compat_parse_obj_as as parse_obj_as
 from deepfos.api.deepmodel import DeepModelAPI
 from deepfos.api.models.deepmodel import (
     ObjectBasicDTO, ObjectParam,
@@ -34,7 +37,9 @@ from deepfos.exceptions import (
 from deepfos.lib import serutils
 from deepfos.lib.asynchronous import future_property, evloop
 from deepfos.lib.decorator import flagmethod, cached_property, lru_cache
-from deepfos.lib.utils import AliasGenerator, to_version_tuple
+from deepfos.lib.utils import (
+    AliasGenerator, to_version_tuple,
+)
 
 __all__ = ['AsyncDeepModel', 'DeepModel', 'to_fields', 'QueryWithArgs']
 
@@ -117,6 +122,7 @@ dm_type_to_edb_scalar = {
     'uuid': 'std::str',
     'json': 'std::json',
 }
+TAB = ' ' * 4
 
 
 class ObjectElement(ObjectParam):
@@ -128,6 +134,7 @@ class ObjectElement(ObjectParam):
 class QueryWithArgs(BaseModel):
     commands: str
     kwargs: Dict[str, Any] = Field(default_factory=dict)
+    globals: Dict[str, Any] = Field(default_factory=dict)
 
 
 class MainField(NamedTuple):
@@ -146,25 +153,25 @@ class MainPgCol(NamedTuple):
 class ConstraintField(BaseModel):
     name: str
     expr: str
-    finalexpr: str = None
-    subjectexpr: str = None
+    finalexpr: Optional[str] = None
+    subjectexpr: Optional[str] = None
 
 
 class NamedField(BaseModel):
-    name: str = None
+    name: Optional[str] = None
 
 
 class NameIdField(BaseModel):
-    id: uuid.UUID = None
-    name: str = None
+    id: Optional[uuid.UUID] = None
+    name: Optional[str] = None
 
 
 class TargetField(BaseModel):
-    id: uuid.UUID = None
+    id: Optional[uuid.UUID] = None
     name: str
     external: bool = False
     annotations: List[Dict[str, str]] = Field(default_factory=list)
-    properties: List[NameIdField] = None
+    properties: Optional[List[NameIdField]] = None
 
     @property
     def is_scalar(self) -> bool:
@@ -184,7 +191,7 @@ class TargetField(BaseModel):
 
 
 class LinkPropField(BaseModel):
-    id: uuid.UUID = None
+    id: Optional[uuid.UUID] = None
     name: str
     target: NamedField
 
@@ -194,15 +201,15 @@ class LinkPropField(BaseModel):
 
 
 class PtrInfo(BaseModel):
-    id: Union[uuid.UUID, Literal['id']] = None
+    id: Optional[Union[uuid.UUID, Literal['id']]] = None
     name: str
     target: TargetField
     properties: List[LinkPropField] = Field(default_factory=list)
-    expr: str = None
-    source_property: NamedField = None
-    target_property: NamedField = None
-    required: bool = False
-    cardinality: str = None
+    expr: Optional[str] = None
+    source_property: Optional[NamedField] = None
+    target_property: Optional[NamedField] = None
+    required: Optional[bool] = False
+    cardinality: Optional[str] = None
     constraints: List[ConstraintField] = Field(default_factory=list)
     annotations: List[Dict[str, str]] = Field(default_factory=list)
 
@@ -252,7 +259,7 @@ _RE_CONSTRAINT_FIELDS = re.compile(r'\((((\.\w+)(,\s+)?)+)\)')
 
 
 class ObjectTypeFrame(BaseModel):
-    id: uuid.UUID = None
+    id: Optional[uuid.UUID] = None
     name: str
     links: List[PtrInfo] = Field(default_factory=list)
     properties: List[PtrInfo] = Field(default_factory=list)
@@ -297,20 +304,43 @@ class ObjectTypeFrame(BaseModel):
         return exclusive
 
 
-def _format_link(df: pd.DataFrame, link_name: str):
-    if all(pd.isnull(df['target'])):
-        return {'target': pd.NA}
-
-    record = df.drop(columns=['source']).set_index('target')
+def _format_link(link_df_fit: pd.DataFrame, link_name: str):
+    if link_df_fit.empty:
+        return pd.Series(dtype=object), False
 
-    if not record.index.is_unique:
+    if link_df_fit.duplicated(subset=['source', 'target']).any():
         raise MultiLinkTargetNotUnique(
             f'Multi Link: [{link_name}] relation dataframe中'
             f'source与target对应存在不唯一性'
         )
 
-    record = record.to_dict(orient='index')
-    return {'prop': record, 'target': list(record.keys())}
+    prop_cols = [col for col in link_df_fit.columns if col not in ['source', 'target']]
+    has_props = bool(prop_cols)
+
+    if has_props:
+        sources = link_df_fit['source'].values
+        targets = link_df_fit['target'].values
+        unique_sources, source_indices = np.unique(sources, return_inverse=True)
+        
+        prop_arrays = {col: link_df_fit[col].values for col in prop_cols}
+        result = {}
+
+        for i in range(len(unique_sources)):
+            idx = source_indices == i
+            source = unique_sources[i]
+            source_targets = targets[idx]
+
+            indices = np.where(idx)[0]
+            prop_dict = {
+                source_targets[j]: {col: prop_arrays[col][indices[j]] for col in prop_cols}
+                for j in range(len(source_targets))
+            }
+            result[source] = {'target': source_targets.tolist(), 'prop': prop_dict}
+        link = pd.Series(result, dtype=object)
+    else:
+        link = link_df_fit.groupby('source')['target'].agg(list)
+
+    return link, has_props
 
 
 class BaseField(PtrInfo):
@@ -370,16 +400,12 @@ class FieldJson(BaseField):
             df[field_name] = df[field_name].apply(self.format_json)
 
     def cast(self, df: pd.DataFrame, field_name: str, direct_access: bool = True):
-        # std::json needed to be cast only when data is from http
-        # since json value will be converted to json string(type: str)
-        # in edgedb python protocol
-        if not direct_access:
-            df[field_name] = df[field_name].apply(self.format_json)
+        pass
 
 
 class FieldInt(BaseField):
     def fit(self, df: pd.DataFrame, field_name: str, raw_pg: bool = False):
-        df[field_name] = pd.to_numeric(df[field_name])
+        df[field_name] = df[field_name].astype(pd.Int64Dtype(), errors='ignore')
 
     def cast(self, df: pd.DataFrame, field_name: str, direct_access: bool = True):
         df[field_name] = df[field_name].astype(pd.Int64Dtype(), errors='ignore')
@@ -483,71 +509,91 @@ def _iter_link_prop_assign(link, business_key, prop_name, prop_type, is_multi):
 def _iter_single_assign(
     field: PtrInfo,
     cast_type: str,
-    target_main_field: Dict[str, MainField]
-):
-    assign_string = f"{field.name} := "
+    target_main_field: Dict[str, MainField],
+    error_on_empty_link: bool = False
+) -> str:
+    """
+    生成单字段赋值语句
+
+    Args:
+        field: 字段信息
+        cast_type: 字段类型
+        target_main_field: 目标字段信息
+        error_on_empty_link: 链接字段值不存在时是否抛出异常
+
+    Returns:
+        赋值语句
+    """
+    assign = f"\n{field.name} := "
     # 设置标量值
     if field.name not in target_main_field:
-        assign_string += f"<{cast_type}>"
+        if field.is_multi:
+            return assign + f"json_array_unpack(item['{field.name}'])"
+
+        assign += f"<{cast_type}>"
 
         if cast_type in NEED_CAST_STR:
-            assign_string += '<std::str>'
+            assign += '<std::str>'
 
-        return assign_string + f"item['{field.name}']"
+        return assign + f"item['{field.name}']"
 
     # 设置link target值
     link = field.name
     main_field = target_main_field[link]
 
     if main_field.props:
-        target = (
-            cast_type + "{" +
-            ",".join(
-                _iter_link_prop_assign(link, main_field.business_key, name,
-                                       field.prop_type[name], main_field.is_multi)
-                for name in main_field.props
-            ) + "}"
+        prop_assigns = ','.join(
+            _iter_link_prop_assign(link, main_field.business_key, name,
+                                   field.prop_type[name], main_field.is_multi)
+            for name in main_field.props
         )
+        prop_block = f" {{{prop_assigns}}}"
     else:
-        target = cast_type
+        prop_block = ""
 
     if main_field.is_multi:
-        assign_string += f"""(
-            select detached {target}
-            filter contains(
-                <array<{main_field.type}>>(json_get(item, '{link}', 'target')),
-                .{main_field.business_key}
-            )
-        )"""
+        link_value = f"each_{link}"
+    else:
+        link_value = f"(json_get(item, '{link}'))"
+
+    if error_on_empty_link:
+        link_expr = f"(<{cast_type}><std::str>{link_value}){prop_block}"
+    else:
+        link_expr = f"(select detached {cast_type}{prop_block}\nfilter .{main_field.business_key} = <std::str>{link_value})"
+
+    if main_field.is_multi:
+        if main_field.props:
+            target_source = f"json_get(item, '{link}', 'target')"
+        else:
+            target_source = f"item['{link}']"
+        
+        assign += 'distinct (\n' + textwrap.indent(textwrap.dedent(f"""\
+        for each_{link} in json_array_unpack({target_source})
+        union (
+            {link_expr}
+        )"""), TAB) + '\n)'
     else:
-        assign_string += f"""assert_single((
-            select detached {target}
-            filter .{main_field.business_key} = <{main_field.type}>(json_get(item, '{link}'))
-        ))"""
+        assign += link_expr
 
-    return assign_string
+    return assign
 
 
 def bulk_insert_by_fields(
     object_name: str,
     field_type: List[PtrInfo],
     target_main_field: Dict[str, MainField],
+    error_on_empty_link: bool = False,
 ):
-    insert_assign_body = ','.join(
-        [
-            _iter_single_assign(field, field.type, target_main_field)
-            for field in field_type
-        ]
-    )
-
-    return f"""
-    with raw_data := <json>to_json(<std::str>${BATCH_INSERT_KW}),
-    for item in json_array_unpack(raw_data) union (
-        insert {object_name} {{
-            {insert_assign_body}
-        }}
-    )
-    """
+    insert_assign_body = ','.join([
+        _iter_single_assign(field, field.type, target_main_field, error_on_empty_link)
+        for field in field_type
+    ])
+    return textwrap.dedent(f"""
+        with raw_data := <json>to_json(<std::str>${BATCH_INSERT_KW}),
+        for item in json_array_unpack(raw_data) union (
+            insert {object_name} {{{textwrap.indent(insert_assign_body, TAB * 4)}
+            }}
+        )""")
 
 
 def bulk_upsert_by_fields(
@@ -555,63 +601,62 @@ def bulk_upsert_by_fields(
     field_type: List[PtrInfo],
     target_main_field: Dict[str, MainField],
     exclusive_fields: Iterable[str],
-    update_fields: Iterable[str]
+    update_fields: Iterable[str],
+    error_on_empty_link: bool = False,
 ):
     conflict_on_fields = map(lambda n: f'.{n}', exclusive_fields)
-
-    insert_assign_body = ','.join(
-        [
-            _iter_single_assign(field, field.type, target_main_field)
-            for field in field_type
-        ]
-    )
+    insert_assign_body = ','.join([
+        _iter_single_assign(field, field.type, target_main_field, error_on_empty_link)
+        for field in field_type
+    ])
     update_assign_body = ','.join(
         [
-            _iter_single_assign(field, field.type, target_main_field)
+            _iter_single_assign(field, field.type, target_main_field, error_on_empty_link)
             for field in field_type if field.name in update_fields
         ]
     )
-
-    return f"""
+    return textwrap.dedent(f"""
         with raw_data := <json>to_json(<std::str>${BATCH_INSERT_KW}),
         for item in json_array_unpack(raw_data) union (
-            insert {object_name} {{
-                {insert_assign_body}
+            insert {object_name} {{{textwrap.indent(insert_assign_body, TAB * 4)}
             }}
             unless conflict on ({','.join(conflict_on_fields)})
             else (
-                update {object_name} set {{
-                    {update_assign_body}
+                update {object_name} set {{{textwrap.indent(update_assign_body, TAB * 5)}
                 }}
             )
-        )
-        """
+        )""")
 
 
 def bulk_update_by_fields(
     object_name: str,
-    business_key: str,
     field_type: List[PtrInfo],
     target_main_field: Dict[str, MainField],
-    update_fields: Iterable[str] = None,
+    match_fields: Iterable[str],
+    update_fields: Iterable[str],
+    error_on_empty_link: bool = False,
 ):
-    update_assign_body = ','.join(
+    update_assign_body = ','.join([
+        _iter_single_assign(field, field.type, target_main_field, error_on_empty_link)
+        for field in field_type if field.name in update_fields
+    ])
+
+    field_type_map = {field.name: field.type for field in field_type}
+    match_str = " and ".join(
         [
-            _iter_single_assign(field, field.type, target_main_field)
-            for field in field_type if field.name in update_fields
+            f".{name} = <{field_type_map.get(name, 'std::str')}>item['{name}']"
+            for name in match_fields
         ]
     )
-
-    return f"""
-        with raw_data := <json>to_json(<std::str>${BATCH_INSERT_KW}),
-        for item in json_array_unpack(raw_data) union (
-            update {object_name} 
-            filter .{business_key} = <std::str>item['{business_key}']
-            set {{
-                {update_assign_body}
-            }}
-        )
-        """
+    return textwrap.dedent(f"""
+    with raw_data := <json>to_json(<std::str>${BATCH_INSERT_KW}),
+    for item in json_array_unpack(raw_data) union (
+        update {object_name} 
+        filter {match_str}
+        set {{{textwrap.indent(update_assign_body, TAB * 3)}
+        }}
+    )
+    """)
 
 
 def format_obj(obj: edgedb.Object) -> ObjectTypeFrame:
@@ -636,25 +681,27 @@ def collect_query_result_structure(
     fields = [
         PtrInfo(
             name=f.name,
-            target=NamedField(name=dm_type_to_edb_scalar.get(f.type, NOT_SCALAR))
+            target=TargetField(name=dm_type_to_edb_scalar.get(f.type, NOT_SCALAR))
         )
         for f in object_info.fields
     ]
-    return ObjectStructure(name='', structure=fields)
+    include_id = len(fields) == 1 and fields[0].name == 'id'
+    return ObjectStructure(name='', structure=fields, include_id=include_id)
 
 
 def collect_frame_desc_structure(desc: Dict[str, str]):
     fields = [
         PtrInfo(
             name=name if isinstance(name, str) else name[0],
-            target=NamedField(
+            target=TargetField(
                 name=tname
                 if isinstance(tname, str) else NOT_SCALAR
             )
         )
         for name, tname in desc.items()
     ]
-    return ObjectStructure(name='', structure=fields)
+    include_id = len(fields) == 1 and fields[0].name == 'id'
+    return ObjectStructure(name='', structure=fields, include_id=include_id)
 
 
 # Copied from edb/pgsql/types.py base_type_name_map
@@ -765,48 +812,74 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
     """DeepModel元素
 
     Args:
-        direct_access: 是否使用直连模式
+        direct_access: 是否使用直连模式，默认为True
+            会结合OPTION.edgedb.dsn是否有值决定是否使用直连模式，如无值，则仍为非直连模式
+            直连模式下，会使用edgedb-python库直连edgedb server，
+            否则会使用DeepModel组件API进行操作
         pg_dsn: PG连接信息
+
     """
     __mangle_docs__ = False
 
-    def __init__(self, direct_access: bool = True, pg_dsn: str = None):  # noqa
+    def __init__(
+        self,
+        direct_access: bool = True,
+        pg_dsn: str = None,
+        **kwargs
+    ):
         self._txn_ = ContextVar('QLTXN')
         self.appmodule = f"app{OPTION.api.header['app']}"
         self.spacemodule = f"space{OPTION.api.header['space']}"
-        self.direct_access = direct_access
+        self.direct_access = direct_access and bool(OPTION.edgedb.dsn)
+        if not self.direct_access:
+            logger.debug('当前DeepModel为非直连模式')
         self.alias = AliasGenerator()
         self.pg_dsn = pg_dsn
+        self._globals = None
+        self._clients = threading.local()
 
     @future_property
-    async def client(self):
-        if self.direct_access:
-            api = await self.wait_for('async_api')
-            ver = await api.extra.version()
-            if to_version_tuple(ver, -1) >= (3, 0, 18, 8, 0):
-                db_info = await api.sharding.database()
-                space = OPTION.api.header['space']
-                if db_info.space != space:
-                    raise ValueError(
-                        f'Space id in sharding database info invalid. '
-                        f'Expected space id: {space}, actual: {db_info.space}'
-                    )
-                dbname = db_info.edgedbName
-            else:
-                dbname = None
-            client = create_async_client(
-                default_module=self.appmodule,
-                dbname=dbname
+    async def _internal_dbname(self):
+        if not self.direct_access:
+            # N.B: only retrieved when direct access is enabled
+            return
+        api = await self.wait_for('async_api')
+        ver = await api.extra.version()
+        if to_version_tuple(ver, 4) < (3, 0, 18, 8, 0):
+            return
+        db_info = await api.sharding.database()
+        space = OPTION.api.header['space']
+        if db_info.space != space:
+            raise ValueError(
+                f'Space id in sharding database info invalid. '
+                f'Expected space id: {space}, actual: {db_info.space}'
             )
-            if user_id := OPTION.api.header.get('user'):
-                client = client.with_globals(
-                    **{
-                        f'{self.spacemodule}::current_user_id':
-                        user_id
-                    }
-                )
+        return db_info.edgedbName
+
+    @property
+    def client(self):
+        if not self.direct_access:
+            self._globals = {}
+            return
+
+        if (client := getattr(self._clients, 'value', None)) is not None:
             return client
 
+        client = create_async_client(
+            default_module=self.appmodule,
+            dbname=self._internal_dbname
+        )
+        if user_id := OPTION.api.header.get('user'):
+            default_globals = {
+                f'{self.spacemodule}::current_user_id':
+                user_id
+            }
+            client = client.with_globals(**default_globals)
+        if self._globals is None:
+            self._globals = client._options.state._globals
+        self._clients.value = client
+        return client
+
     @future_property
     async def element_info(self):
         """元素信息"""
@@ -899,12 +972,20 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         """
 
         if self.direct_access:
-            logger.opt(lazy=True).debug(f"Query: [{ql}], \nkwargs: [{kwargs}].")
-            _, result = await self.client.query(ql, **kwargs)
+            logger.opt(lazy=True).debug(f"Query: [{ql}],\n"
+                                        f"kwargs: [{kwargs}],\n"
+                                        f"globals: [{self._globals}].")
+            client = self.client
+            client._options.state._globals = self._globals
+            _, result = await client.query(ql, **kwargs)
             return result
 
-        result = await AsyncDeepModel.query(self, ql, **kwargs)
-        return serutils.deserialize(result)
+        result = await self._http_query(ql, **kwargs)
+        field_info = {
+            fi.name: fi.type if fi.fields is None else fi.fields
+            for fi in result.objectInfos[0].fields
+        } if result.objectInfos else {}
+        return serutils.deserialize(result.json_, field_info)
 
     async def query(self, ql: str, **kwargs) -> List[Any]:
         """执行ql查询语句，得到序列化后的结果
@@ -934,8 +1015,12 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
 
         """
         if self.direct_access:
-            logger.opt(lazy=True).debug(f"Query: [{ql}], \nkwargs: [{kwargs}].")
-            frame_desc, result = await self.client.query(ql, **kwargs)
+            logger.opt(lazy=True).debug(f"Query: [{ql}],\n"
+                                        f"kwargs: [{kwargs}],\n"
+                                        f"globals: [{self._globals}].")
+            client = self.client
+            client._options.state._globals = self._globals
+            frame_desc, result = await client.query(ql, **kwargs)
             return serutils.serialize(
                 result, ctx=serutils.Context(frame_desc=frame_desc)
             )
@@ -982,7 +1067,17 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         
         """
         if self.direct_access:
-            frame_desc, data = await self.client.query(ql, **kwargs)
+            client = self.client
+            client._options.state._globals = self._globals
+            frame_desc, data = await client.query(ql, **kwargs)
+            # set of unnamed tuple
+            if isinstance(frame_desc, list):
+                return pd.DataFrame(
+                    data=serutils.serialize(
+                        data, ctx=serutils.Context(frame_desc=frame_desc, query_df=True)
+                    ),
+                    columns=[str(i) for i in range(len(frame_desc))]
+                )
 
             data = pd.DataFrame(data=serutils.serialize(
                 data, ctx=serutils.Context(frame_desc=frame_desc, query_df=True)
@@ -995,7 +1090,7 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         else:
             result = await self._http_query(ql, **kwargs)
             # No object structure info
-            if result.objectInfos is None:
+            if not result.objectInfos:
                 return pd.DataFrame(data=result.json_)
 
             data = pd.DataFrame(
@@ -1015,6 +1110,9 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
     query_object.__doc__ = query_object.__doc__ + DOC_ARGS_KWARGS
     query_df.__doc__ = query_df.__doc__ + DOC_ARGS_KWARGS
 
+    def _ensure_client(self):
+        self.client # noqa
+
     @txn_support
     async def execute(
         self,
@@ -1030,8 +1128,15 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
                  会自动用作所有string形式ql的参数
 
         """
+        qls_with_args = self._collect_execute_qls(qls, kwargs)
+        return await self._maybe_exec_qls(qls_with_args)
+
+    def _collect_execute_qls(self, qls, kwargs):
+        self._ensure_client()
         if isinstance(qls, str):
-            qls_with_args = [QueryWithArgs(commands=qls, kwargs=kwargs)]
+            qls_with_args = [QueryWithArgs(
+                commands=qls, kwargs=kwargs, globals=self._globals
+            )]
         else:
             qls_with_args = []
             seen_kwargs_key = set()
@@ -1049,11 +1154,12 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
                         seen_kwargs_key = seen_kwargs_key.union(ql.kwargs.keys())
 
                 elif isinstance(ql, str):
-                    qls_with_args.append(QueryWithArgs(commands=ql, kwargs=kwargs))
+                    qls_with_args.append(QueryWithArgs(
+                        commands=ql, kwargs=kwargs, globals=self._globals
+                    ))
                 else:
                     raise TypeError(f'qls参数中出现类型非法成员：{type(ql)}')
-
-        return await self._maybe_exec_qls(qls_with_args)
+        return qls_with_args
 
     execute.__doc__ = execute.__doc__ + DOC_ARGS_KWARGS
 
@@ -1085,16 +1191,31 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             return affected
 
         result = []
-        async for tx in self.client.transaction():
+        client = self.client
+        client._options.state._globals = self._globals
+        async for tx in client.transaction():
             async with tx:
                 for ql in qls_with_args:
                     logger.opt(lazy=True).debug(
-                        f"Execute QL: [{ql.commands}], \nkwargs: [{ql.kwargs}]."
+                        f"Execute QL: [{ql.commands}],"
+                        f"\nkwargs: [{ql.kwargs}],"
+                        f"\nglobals: [{ql.globals}]."
                     )
-                    desc, affected = await tx.execute(ql.commands, **ql.kwargs)
-                    result.append(serutils.serialize(
-                        affected, ctx=serutils.Context(frame_desc=desc)
-                    ))
+                    if ql.globals:
+                        bak_cli = tx._client
+                        tx._client = tx._client.with_globals(**ql.globals)
+                        try:
+                            desc, affected = await tx.execute(ql.commands, **ql.kwargs)
+                            result.append(serutils.serialize(
+                                affected, ctx=serutils.Context(frame_desc=desc)
+                            ))
+                        finally:
+                            tx._client = bak_cli
+                    else:
+                        desc, affected = await tx.execute(ql.commands, **ql.kwargs)
+                        result.append(serutils.serialize(
+                            affected, ctx=serutils.Context(frame_desc=desc)
+                        ))
         if len(result) == 1:
             return result[0]
         return result
@@ -1122,13 +1243,14 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         return await self._execute(qls_with_args)
 
     @staticmethod
-    def _valid_data(data, object_name, relation, structure):
-        required_fields = set(map(
-            lambda f: f.name,
-            filter(lambda f: f.required, structure.fields.values())
-        ))
-        if missing_fields := (required_fields - set(data.columns)):
-            raise RequiredFieldUnfilled(f'缺少必填字段: {missing_fields}')
+    def _valid_data(data, object_name, relation, structure, check_required=True):
+        if check_required:
+            required_fields = set(map(
+                lambda f: f.name,
+                filter(lambda f: f.required, structure.fields.values())
+            ))
+            if missing_fields := (required_fields - set(data.columns).union(relation)):
+                raise RequiredFieldUnfilled(f'缺少必填字段: {missing_fields}')
 
         if not relation:
             return
@@ -1176,6 +1298,218 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             if exclusive not in valid_exclusive:
                 raise ValueError(f"exclusive fields: {exclusive_fields} 没有相应唯一约束")
 
+    async def _get_bkey(
+        self,
+        obj: Union[ObjectTypeFrame, TargetField],
+        source: str = None,
+        name: str = None
+    ) -> str:
+        # 如可在object结构的annotations中取业务主键，则优先取，否则走接口
+        if obj.info and BUSINESS_KEY in obj.info:
+            return obj.info[BUSINESS_KEY]
+        elif (code := obj.normalized_name) in self.model_objects:
+            return self.model_objects[code].businessKey
+
+        assert isinstance(obj, TargetField)
+        # Link 至非本应用对象，需单独查询
+        tgt = ObjectElement.construct_from(self.model_objects[source]).links[name]
+        tgt_model_info = await self.async_api.object.info(
+            app=tgt.targetApp, object_code=tgt.targetObjectCode
+        )
+        return tgt_model_info.businessKey
+
+    async def _collect_bulk_field_info(self, object_name, structure, data, relation):
+        field_info = []
+        tgt_main_field = {}
+        for field in structure.fields.values():
+            if field.name not in data.columns:
+                continue
+
+            field_info.append(field)
+
+            if not field.is_link:
+                continue
+
+            is_multi = field.is_multi_link
+            name = field.name
+            # 链接至其他对象，记录目标对象信息
+            if is_multi:
+                if name not in relation:
+                    raise ValueError(
+                        f'对象[{object_name}]的多选链接:[{name}]未定义在relation中'
+                    )
+                link_props = set(relation[name].columns).intersection(field.props)
+            else:
+                link_props = set(
+                    c[len(f'{name}@')::]
+                    for c in data.columns if c.startswith(f'{name}@')
+                ).intersection(field.props)
+            tgt_bkey = await self._get_bkey(field.target, object_name, name)
+            tgt_main_field[name] = MainField(tgt_bkey, is_multi, link_props)
+        return field_info, tgt_main_field
+
+    def _ql_payload(self, data: pd.DataFrame, ql: str,):
+        self._ensure_client()
+        kw_name = self.alias.get(BATCH_INSERT_KW)
+        return QueryWithArgs(
+            commands=ql.replace(f'${BATCH_INSERT_KW}', f'${kw_name}'),
+            kwargs={kw_name: data.to_json(
+                orient='records', double_precision=15,
+                force_ascii=False, default_handler=str
+            )},
+            globals=self._globals,
+        )
+
+    @staticmethod
+    def _split_self_link(data, relation, structure, bkey):
+        self_link_dfs = {}
+        for name in structure.self_link_fields:
+            field = structure.fields[name]
+            if (link_df := relation.get(name)) is not None:
+                link_props = set(link_df.columns).intersection(field.props)
+                self_link_dfs[name] = (
+                    structure.fit(data[[bkey, name]]),
+                    MainField(bkey, field.is_multi_link, link_props)
+                )
+                data = data.drop(columns=[name])
+            elif name in data.columns:
+                link_prop_cols = []
+                link_props = []
+
+                for col in data.columns:
+                    if (
+                        col.startswith(f'{name}@')
+                        and ((prop_name := col[len(f'{name}@')::]) in field.props)
+                    ):
+                        link_prop_cols.append(col)
+                        link_props.append(prop_name)
+
+                self_link_dfs[name] = (
+                    structure.fit(data[[bkey, name, *link_prop_cols]]),
+                    MainField(bkey, field.is_multi_link, link_props)
+                )
+                data = data.drop(columns=[name, *link_prop_cols])
+        return data, self_link_dfs
+
+    @staticmethod
+    def _merge_relation(data, relation, structure, bkey):
+        for name, link_df in relation.items():
+            link_df = link_df.dropna(how='any', subset=['target', 'source'])
+            if name not in structure.fields:
+                continue
+            field = structure.fields[name]
+            valid_cols = list({'source', 'target', *field.props} & set(link_df.columns))
+            link_df = link_df[valid_cols]
+            # for fit only
+            temp_structure = ObjectStructure(
+                field.type,
+                [
+                    PtrInfo(name='source', target=TargetField(name='std::str')),
+                    PtrInfo(name='target', target=TargetField(name='std::str')),
+                    *[PtrInfo(**prop.dict()) for prop in field.properties]
+                ]
+            )
+            link_df = temp_structure.fit(link_df)
+            link, has_props = _format_link(link_df, name)
+
+            if not has_props:
+                data = data.drop(columns=[name], errors='ignore')
+                data = data.join(link.to_frame(name), on=bkey, how='left')
+                mask = data[name].isna()
+                if mask.any():
+                    empty_series = pd.Series([[]] * mask.sum(), index=data[mask].index, dtype=object)
+                    data.loc[mask, name] = empty_series
+            else:
+                bkey_values = data[bkey].values
+                mapped_values = np.array([link.get(key, []) for key in bkey_values], dtype=object)
+                data[name] = mapped_values
+            
+        return data
+
+    async def _collect_bulk_qls(
+        self,
+        object_name: str,
+        data: pd.DataFrame,
+        relation: Dict[str, pd.DataFrame] = None,
+        chunk_size: int = 500,
+        enable_upsert: bool = False,
+        update_fields: Iterable[str] = None,
+        exclusive_fields: Iterable[str] = None,
+        match_fields: Iterable[str] = None,
+        insert: bool = True,
+        error_on_empty_link: bool = False
+    ) -> List[List[QueryWithArgs]]:
+        if object_name in self.objects:
+            obj = self.objects[object_name]
+        else:
+            raise ObjectNotExist(
+                f'DeepModel对象[{object_name}]在当前应用不存在，无法插入数据'
+            )
+        if obj.external:
+            raise ExternalObjectReadOnly('外部对象只可读')
+
+        structure = ObjectStructure(name=obj.name, structure=obj.fields.values())
+        relation = relation or {}
+        self._valid_data(data, object_name, relation, structure, check_required=insert)
+
+        bkey = await self._get_bkey(obj)
+        if bkey not in data.columns:
+            raise RequiredFieldUnfilled(f'缺少业务主键[{bkey}]')
+
+        # data拼接relation df
+        data = self._merge_relation(data, relation, structure, bkey)
+        # 从data中分离出self-link更新信息
+        data, self_link_dfs = self._split_self_link(data, relation, structure, bkey)
+        field_info, tgt_main_field = await self._collect_bulk_field_info(
+            object_name, structure, data, relation
+        )
+        field_names = set(map(lambda f: f.name, field_info))
+        if insert:
+            if enable_upsert:
+                self._valid_upsert(obj, field_names, bkey, exclusive_fields, update_fields)
+
+            exclusive_fields = set(exclusive_fields or {bkey}) & set(field_names)
+            update_fields = set(update_fields or (field_names - {bkey})) & set(field_names)
+            if enable_upsert and update_fields:
+                bulk_ql = bulk_upsert_by_fields(
+                    object_name, field_info, tgt_main_field,
+                    exclusive_fields, update_fields, error_on_empty_link
+                )
+            else:
+                bulk_ql = bulk_insert_by_fields(object_name, field_info, tgt_main_field, error_on_empty_link)
+        else:
+            if missing := (set(match_fields or [bkey]) - set(field_names)):
+                raise ValueError(f"match fields: {missing} 不在提供的数据中")
+
+            match_fields = set(match_fields or [bkey]) & set(field_names)
+            if to_upd := (field_names - match_fields):
+                bulk_ql = bulk_update_by_fields(
+                    object_name, field_info, tgt_main_field,
+                    match_fields, to_upd, error_on_empty_link
+                )
+            else:
+                bulk_ql = None
+        qls = []
+        self._ensure_client()
+        if chunk_size is None:
+            chunk_size = len(data)
+        for i in range(0, len(data), chunk_size):
+            part = structure.fit(data.iloc[i: i + chunk_size])
+            ql_chunk = []
+            # Ignore bulk_ql when only update multi links
+            if bulk_ql is not None:
+                ql_chunk = [self._ql_payload(part, bulk_ql)]
+            for update_field, (update_df, main_field) in self_link_dfs.items():
+                field = structure.fields[update_field]
+                update_ql = bulk_update_by_fields(
+                    object_name, [field], {update_field: main_field},
+                    [bkey], [update_field]
+                )
+                update_part = update_df.iloc[i: i + chunk_size]
+                ql_chunk.append(self._ql_payload(update_part, update_ql))
+            qls.append(ql_chunk)
+        return qls
+
     @txn_support
     async def insert_df(
         self,
@@ -1186,6 +1520,8 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         enable_upsert: bool = False,
         update_fields: Iterable[str] = None,
         exclusive_fields: Iterable[str] = None,
+        commit_per_chunk: bool = False,
+        error_on_empty_link: bool = False,
     ) -> None:
         """以事务执行基于DataFrame字段信息的批量插入数据
 
@@ -1206,6 +1542,12 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             exclusive_fields: upsert句式下update的exclusive fields列表，
                             涉及的fields需出现在data或relation中，
                             默认为业务主键
+            commit_per_chunk: 每次插入后是否提交事务，
+                            默认为False，即所有数据插入后再提交事务
+                            该参数仅在非start transaction上下文中生效
+            error_on_empty_link: 链接字段值不存在时是否抛出异常，
+                            默认为False，即不检查链接目标是否存在
+                            当设置为True时，会检查链接目标是否存在，不存在则抛出异常
 
         Notes:
 
@@ -1278,94 +1620,16 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             logger.info("data为空，无DML执行")
             return
 
-        if object_name in self.objects:
-            obj = self.objects[object_name]
-        else:
-            raise ObjectNotExist(
-                f'DeepModel对象[{object_name}]在当前应用不存在，无法插入数据'
-            )
-        if obj.external:
-            raise ExternalObjectReadOnly('外部对象只可读')
-
-        structure = ObjectStructure(name=obj.name, structure=obj.fields.values())
-
-        self._valid_data(data, object_name, relation, structure)
-
-        relation = relation or {}
-        bkey = await self._get_bkey(obj)
-        # data拼接relation df
-        data = self._merge_relation(data, relation, structure, bkey)
-        # 从data中分离出self-link更新信息
-        data, self_link_dfs = self._split_self_link(data, relation, structure, bkey)
-
-        field_info = []
-        tgt_main_field = {}
-        # 准备bulk insert所需field信息
-        for field in structure.fields.values():
-            if field.name not in data.columns:
-                continue
-
-            field_info.append(field)
-
-            if not field.is_link:
-                continue
-
-            is_multi = field.is_multi_link
-            name = field.name
-            # 链接至其他对象，记录目标对象信息
-            if is_multi:
-                link_props = set(relation[name].columns).intersection(field.props)
-            else:
-                link_props = set(
-                    c[len(f'{name}@')::]
-                    for c in data.columns if c.startswith(f'{name}@')
-                ).intersection(field.props)
-            tgt_bkey = await self._get_bkey(field.target, object_name, name)
-            tgt_main_field[name] = MainField(tgt_bkey, is_multi, link_props)
-
-        field_names = set(map(lambda f: f.name, field_info))
-        if enable_upsert:
-            self._valid_upsert(obj, field_names, bkey, exclusive_fields, update_fields)
-
-        exclusive_fields = set(exclusive_fields or {bkey}) & set(field_names)
-        update_fields = set(update_fields or (field_names- {bkey})) & set(field_names)
-        if enable_upsert and update_fields:
-            insert_ql = bulk_upsert_by_fields(
-                object_name, field_info, tgt_main_field,
-                exclusive_fields, update_fields
-            )
+        qls = await self._collect_bulk_qls(
+            object_name, data, relation, chunksize,
+            enable_upsert, update_fields, exclusive_fields,
+            insert=True, error_on_empty_link=error_on_empty_link
+        )
+        if commit_per_chunk:
+            for ql_chunk in qls:
+                await self.execute(ql_chunk)
         else:
-            insert_ql = bulk_insert_by_fields(object_name, field_info, tgt_main_field)
-
-        qls = []
-        self._collect_qls(structure.fit(data), insert_ql, chunksize, qls)
-        if self_link_dfs:
-            for update_field, (update_df, main_field) in self_link_dfs.items():
-                field = structure.fields[update_field]
-                update_ql = bulk_update_by_fields(
-                    object_name, bkey, [field],
-                    {update_field: main_field}, [update_field]
-                )
-                self._collect_qls(update_df, update_ql, chunksize, qls)
-
-        await self.execute(qls)
-
-    def _collect_qls(
-        self,
-        data: pd.DataFrame,
-        ql: str,
-        chunksize: int,
-        qls: List[QueryWithArgs]
-    ):
-        for i in range(0, len(data), chunksize):
-            part = data.iloc[i: i + chunksize]
-            kw_name = self.alias.get(BATCH_INSERT_KW)
-            qls.append(QueryWithArgs(
-                commands=ql.replace(
-                    f'${BATCH_INSERT_KW}', f'${kw_name}'
-                ),
-                kwargs={kw_name: part.to_json(orient='records', double_precision=15)}
-            ))
+            await self.execute(list(chain(*qls)))
 
     async def get_object(
         self,
@@ -1395,80 +1659,6 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
 
         return format_obj(objs[0])
 
-    async def _get_bkey(
-        self,
-        obj: Union[ObjectTypeFrame, TargetField],
-        source: str = None,
-        name: str = None
-    ) -> str:
-        # 如可在object结构的annotations中取业务主键，则优先取，否则走接口
-        if obj.info and BUSINESS_KEY in obj.info:
-            return obj.info[BUSINESS_KEY]
-        elif (code := obj.normalized_name) in self.model_objects:
-            return self.model_objects[code].businessKey
-
-        assert isinstance(obj, TargetField)
-        # Link 至非本应用对象，需单独查询
-        tgt = ObjectElement.construct_from(self.model_objects[source]).links[name]
-        tgt_model_info = await self.async_api.object.info(
-            app=tgt.targetApp, object_code=tgt.targetObjectCode
-        )
-        return tgt_model_info.businessKey
-
-    @staticmethod
-    def _split_self_link(data, relation, structure, bkey):
-        self_link_dfs = {}
-        for name in structure.self_link_fields:
-            field = structure.fields[name]
-            if (link_df := relation.get(name)) is not None:
-                link_props = set(link_df.columns).intersection(field.props)
-                self_link_dfs[name] = (
-                    structure.fit(data[[bkey, name]]),
-                    MainField(bkey, field.is_multi_link, link_props)
-                )
-                data = data.drop(columns=[name])
-            elif name in data.columns:
-                link_prop_cols = []
-                link_props = []
-
-                for col in data.columns:
-                    if (
-                        col.startswith(f'{name}@')
-                        and ((prop_name := col[len(f'{name}@')::]) in field.props)
-                    ):
-                        link_prop_cols.append(col)
-                        link_props.append(prop_name)
-
-                self_link_dfs[name] = (
-                    structure.fit(data[[bkey, name, *link_prop_cols]]),
-                    MainField(bkey, field.is_multi_link, link_props)
-                )
-                data = data.drop(columns=[name, *link_prop_cols])
-        return data, self_link_dfs
-
-    @staticmethod
-    def _merge_relation(data, relation, structure, bkey):
-        for name, link_df in relation.items():
-            if name not in structure.fields:
-                continue
-            field = structure.fields[name]
-            valid_cols = list({'source', 'target', *field.props} & set(link_df.columns))
-            link_df = link_df[valid_cols]
-            # for fit only
-            temp_structure = ObjectStructure(
-                field.type,
-                [
-                    PtrInfo(name='source', target=TargetField(name='std::str')),
-                    PtrInfo(name='target', target=TargetField(name='std::str')),
-                    *[PtrInfo(**prop.dict()) for prop in field.properties]
-                ]
-            )
-            link_df = temp_structure.fit(link_df)
-            link = link_df.groupby('source').apply(_format_link, link_name=name)
-            data = data.drop(columns=[name], errors='ignore')
-            data = data.join(link.to_frame(name), on=bkey)
-        return data
-
     async def insert_df_pg(
         self,
         object_name: str,
@@ -1584,6 +1774,49 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
         finally:
             await conn.close()
 
+    @txn_support
+    async def update_df(
+        self,
+        object_name: str,
+        data: pd.DataFrame,
+        relation: Dict[str, pd.DataFrame] = None,
+        chunksize: int = 500,
+        match_fields: Iterable[str] = None,
+        commit_per_chunk: bool = False,
+    ) -> None:
+        """以事务执行基于DataFrame字段信息的批量更新数据
+
+        将以业务主键作为匹配条件，除业务主键以外的字段将为update fields
+
+        Args:
+            object_name: 被更新数据的对象名，需属于当前应用
+            data: 要更新的数据，若有single link property，
+                  则以列名为link_name@link_property_name的形式提供
+            relation: 如有multi link，提供该字典用于补充link target信息，
+                    键为link字段名，值为映射关系的DataFrame
+                    DataFrame中的source列需为插入对象的业务主键，
+                    target列需为link target的业务主键，
+                    若有link property，则以property名为列名，提供在除source和target的列中
+            chunksize: 单次最大行数
+            match_fields: update的匹配列表，涉及的fields需出现在data或relation中，默认为业务主键
+            commit_per_chunk: 每次插入后是否提交事务，
+                            默认为False，即所有数据插入后再提交事务
+                            该参数仅在非start transaction上下文中生效
+        """
+        if data.empty:
+            logger.info("data为空，无DML执行")
+            return
+
+        qls = await self._collect_bulk_qls(
+            object_name, data, relation, chunksize,
+            match_fields=match_fields, insert=False
+        )
+        if commit_per_chunk:
+            for ql_chunk in qls:
+                await self.execute(ql_chunk)
+        else:
+            await self.execute(list(chain(*qls)))
+
     @asynccontextmanager
     async def start_transaction(self, flatten: bool = False):
         """开启事务
@@ -1622,7 +1855,7 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
 
         Important:
 
-            仅 :func:`insert_df` :func:`execute` 方法支持在事务中执行
+            仅 :func:`insert_df` :func:`update_df` :func:`execute` 方法支持在事务中执行
 
         """
         try:
@@ -1660,12 +1893,18 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             finally:
                 raise NotImplemented('非直连模式不支持设置state信息')
         else:
-            bak_cli = self.client
+            if self._globals is None:
+                bak_globals = self.client._options.state._globals
+            else:
+                bak_globals = self._globals
             try:
-                self.client = self.client.with_globals(**globals_)
+                client = self.client
+                client._options.state._globals = bak_globals
+                client = client.with_globals(**globals_)
+                self._globals = client._options.state._globals
                 yield
             finally:
-                self.client = bak_cli
+                self._globals = bak_globals
 
     @contextmanager
     def without_globals(self, *global_names):
@@ -1675,19 +1914,26 @@ class AsyncDeepModel(ElementBase[DeepModelAPI]):
             finally:
                 raise NotImplemented('非直连模式不支持设置state信息')
         else:
-            bak_cli = self.client
+            if self._globals is None:
+                bak_globals = self.client._options.state._globals
+            else:
+                bak_globals = self._globals
             try:
-                self.client = self.client.without_globals(*global_names)
+                client = self.client
+                client._options.state._globals = bak_globals
+                client = client.without_globals(*global_names)
+                self._globals = client._options.state._globals
                 yield
             finally:
-                self.client = bak_cli
+                self._globals = bak_globals
 
 
 class DeepModel(AsyncDeepModel, metaclass=SyncMeta):
     synchronize = (
         'query_object', 'query', 'query_df',
         'execute', 'get_object',
-        'insert_df', 'insert_df_pg'
+        'insert_df', 'insert_df_pg',
+        'update_df',
     )
 
     if TYPE_CHECKING:  # pragma: no cover
@@ -1723,6 +1969,8 @@ class DeepModel(AsyncDeepModel, metaclass=SyncMeta):
             enable_upsert: bool = False,
             update_fields: Iterable[str] = None,
             exclusive_fields: Iterable[str] = None,
+            commit_per_chunk: bool = False,
+            error_on_empty_link: bool = False,
         ) -> None:
             ...
 
@@ -1737,6 +1985,17 @@ class DeepModel(AsyncDeepModel, metaclass=SyncMeta):
         ) -> None:
             ...
 
+        def update_df(
+            self,
+            object_name: str,
+            data: pd.DataFrame,
+            relation: Dict[str, pd.DataFrame] = None,
+            chunksize: int = 500,
+            match_fields: Iterable[str] = None,
+            commit_per_chunk: bool = False,
+        ) -> None:
+            ...
+
     @contextmanager
     def start_transaction(self, flatten: bool = False):
         """开启事务