AHj[UddlmZddlZddlmZmZmZddlmZm Z ddlm Z ddlm Z ddlmZddlmZdd lmZdd lmZdd lmZmZdd lmZdd lmZmZddlmZddl m!Z!ddl"m#Z#ejHe%5ddl&m'Z'ddderddl(Z(ddl)m*Z*m+Z+m,Z,ddl-m.Z.ddlm/Z/m0Z0m1Z1m2Z2e(jfdk\rddlm4Z4nddl5m4Z4ee!ze#ze j>ze jFe/ze jlze jnzZ8de9d<dgZ:ddZ;d dZy#1swYxYw)") annotationsN) TYPE_CHECKINGGenericoverload)_check_for_pandas_check_for_pyarrow)pandas)pyarrow) FrameType)deprecate_renamed_parameter) is_pycapsule)issue_unstable_warning)_get_stack_localsqualified_type_name)wrap_ldf) from_arrow from_pandas) DataFrame) LazyFrame)Series) PySQLContext)Callable CollectionMapping) TracebackType)AnyFinalLiteral TypeAlias) )SelfrCompatibleFrameType SQLContextc t|xst|txspt|xr*t|tj tj fxs7t|xr*t|tjtjfS)z2Check if the object can be converted to DataFrame.) r isinstancerrpdrrrpaTable RecordBatch)objs J/root/tools/cai/cai_env/lib/python3.12/site-packages/polars/sql/context.py_compatible_framer-3sq S U c9 % U c " Qz# bii7P'Q U s # S 32>>8R(S cnt|ttfr|jSt|tr|j jSt |ret|tjtjfr;tt|x}tr|j }|jSt|s5t|rCt|tjtjfrt|jSdt|}t!|)z'Return LazyFrame from compatible input.zunrecognised frame type: )r&rrlazyrto_framerr'rr rr(r)r*rr ValueError)r+framemsgs r,_ensure_lazyframer5=s# 9-.xxz C ||~""$$ 3 JsR\\2994M$N {3//e 8NN$Ezz| c 3JsRXXr~~4N$O###%%)*=c*B)CDor.) n_objectsnamedcP|rtntttf}t |||S)z5Return compatible frame objects from the local stack.)of_typer6r7)r-rrrr)all_compatibler6r7r9s r,_get_frame_localsr;Ps$$2 9f7UG W  OOr.ceZdZUdZded<ded<ded<e d,dd d  d-d Ze d,dd  d.dZe d,dd  d/dZedd d d0d d d  d1dZeed d d2dZ eed3dZ eed4dZ ed d d4dZ d5dZ d6dZ d7dZ edd d8dZ e d9dZ e d:dZ edd d;d Z e dd#Z dd d>d$Z d?d%Z d0d&d' d@d(Z d0 dAd)ZdBd*ZdCd+Zy)Dr$a  Run SQL queries against DataFrame, LazyFrame, and Series data. .. warning:: This functionality is considered **unstable**, although it is close to being considered stable. It may be changed at any point without it being considered a breaking change. r_ctxtz Final[bool]_eager_executionzlist[set[str]]_tables_scope_stack.F)register_globalseagerrAc yNselfframesr@rA named_framess r,__init__zSQLContext.__init__or.)r@c yrCrDrEs r,rIzSQLContext.__init__yrJr.c yrCrDrEs r,rIzSQLContext.__init__rJr.eager_executionz0.20.31)versionNc ,tdtj|_||_t |xsi}|r1t djD]\}}||vs ||vs|||<|s|r#|j||j|yy)u Initialize a new `SQLContext`. .. versionchanged:: 0.20.31 The `eager_execution` parameter was renamed `eager`. Parameters ---------- frames A `{name:frame, ...}` mapping which can include Polars frames *and* pandas DataFrames, Series and pyarrow Table and RecordBatch objects. register_globals Register compatible objects (polars DataFrame, LazyFrame, and Series) found in the globals, automatically mapping their variable name to a table name. To register other objects (pandas/pyarrow data) pass them explicitly, or call the `execute_global` classmethod. If given an integer then only the most recent "n" objects found will be registered. eager If True, returns execution results as `DataFrame` instead of `LazyFrame`. (Note that the query itself is always executed in lazy-mode; this parameter impacts whether :meth:`execute` returns an eager or lazy result frame). **named_frames Named eager/lazy frames, provided as kwargs. Examples -------- >>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["x", None, "z"]}) >>> res = pl.SQLContext(frame=lf).execute( ... "SELECT b, a*2 AS two_a FROM frame WHERE b IS NOT NULL" ... ) >>> res.collect() shape: (2, 2) ┌─────┬───────┐ │ b ┆ two_a │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═══════╡ │ x ┆ 2 │ │ z ┆ 6 │ └─────┴───────┘ zY`SQLContext` is considered **unstable**, although it is close to being considered stable.Fr:N) rrnewr=r>dictr;itemsupdate register_many)rFrGr@rArHnamer+s r,rIzSQLContext.__init__sd  g "%%' %fl# .$eg - cv%$l*B),L&  - \ MM, '   v &"r.)rAcyrCrDclsqueryrAs r,execute_globalzSQLContext.execute_globalsr.cyrCrDrXs r,r[zSQLContext.execute_globalsORr.cyrCrDrXs r,r[zSQLContext.execute_globalsRUr.cttj|dd}td|}||d5}|j ||cdddS#1swYyxYw)u Immediately execute a SQL query, automatically registering frame globals. Notes ----- * This convenience method automatically registers all compatible objects in the local stack that are referenced in the query, mapping their variable name to a table name. Note that in addition to polars DataFrame, LazyFrame, and Series this method *also* registers pandas DataFrame, Series, and pyarrow Table and RecordBatch objects. * Instead of calling this classmethod you should consider using `pl.sql`, which will use this code internally. Parameters ---------- query A valid SQL query string. eager If True, returns execution results as `DataFrame` instead of `LazyFrame`. (Note that the query itself is always executed in lazy-mode). Examples -------- >>> import pandas as pd >>> df = pl.LazyFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) >>> df_pandas = pd.DataFrame({"a": [2, 3, 4], "c": [7, 8, 9]}) Join a polars LazyFrame with a pandas DataFrame (note use of the preferred `pl.sql` method, which is equivalent to `SQLContext.execute_global`): >>> pl.sql("SELECT df.*, c FROM df JOIN df_pandas USING(a)").collect() shape: (2, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ 2 ┆ 5 ┆ 7 │ │ 3 ┆ 6 ┆ 8 │ └─────┴─────┴─────┘ FT)include_schemaunique)r:r7)rGr@)rZrAN)setrtable_identifiersr;execute)rYrZrA table_namesrHctxs r,r[zSQLContext.execute_globalse^  * *$  )KP  u = 9;;U%;8 9 9 9s AAct|dg|_|jjt|j |S)zITrack currently registered tables on scope entry; supports nested scopes.r?)getattrr?appendratablesrFs r, __enter__zSQLContext.__enter__s8#*41F#K    ''DKKM(:; r.c|jt|j|jj z y)z Unregister any tables created within the given scope on context exit. See Also -------- unregister )namesN) unregisterrarir?pop)rFexc_typeexc_valexc_tbs r,__exit__zSQLContext.__exit__ s7 t{{}%(@(@(D(D(FF  r.cZt|j}d|dt|ddS)Nz)lenriid)rFn_tabless r,__repr__zSQLContext.__repr__1s-t{{}%%hZwr$xl!DDr.cyrCrDrFrZrAs r,rczSQLContext.execute8r.cyrCrDr|s r,rczSQLContext.execute=r}r.cyrCrDr|s r,rczSQLContext.executeBr}r.cyrCrDr|s r,rczSQLContext.executeGr}r.cyrCrDr|s r,rczSQLContext.executeLr}r.cyrCrDr|s r,rczSQLContext.executeQr}r.cyrCrDr|s r,rczSQLContext.executeVs!$r.ct|jj|}|s |jr|j S|S)u Parse the given SQL query and execute it against the registered frame data. Parameters ---------- query A valid string SQL query. eager Apply the query eagerly, returning `DataFrame` instead of `LazyFrame`. If unset, the value of the init-time "eager" parameter will be used. Note that the query itself is always executed in lazy-mode; this parameter only impacts the type of the returned frame. Examples -------- Declare frame data and register with a SQLContext: >>> df = pl.DataFrame( ... data=[ ... ("The Godfather", 1972, 6_000_000, 134_821_952, 9.2), ... ("The Dark Knight", 2008, 185_000_000, 533_316_061, 9.0), ... ("Schindler's List", 1993, 22_000_000, 96_067_179, 8.9), ... ("Pulp Fiction", 1994, 8_000_000, 107_930_000, 8.9), ... ("The Shawshank Redemption", 1994, 25_000_000, 28_341_469, 9.3), ... ], ... schema=["title", "release_year", "budget", "gross", "imdb_score"], ... orient="row", ... ) >>> ctx = pl.SQLContext(films=df) Execute a SQL query against the registered frame data: >>> ctx.execute( ... ''' ... SELECT title, release_year, imdb_score ... FROM films ... WHERE release_year > 1990 ... ORDER BY imdb_score DESC ... ''', ... eager=True, ... ) shape: (4, 3) ┌──────────────────────────┬──────────────┬────────────┐ │ title ┆ release_year ┆ imdb_score │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ f64 │ ╞══════════════════════════╪══════════════╪════════════╡ │ The Shawshank Redemption ┆ 1994 ┆ 9.3 │ │ The Dark Knight ┆ 2008 ┆ 9.0 │ │ Schindler's List ┆ 1993 ┆ 8.9 │ │ Pulp Fiction ┆ 1994 ┆ 8.9 │ └──────────────────────────┴──────────────┴────────────┘ Execute a GROUP BY query: >>> ctx.execute( ... ''' ... SELECT ... MAX(release_year // 10) * 10 AS decade, ... SUM(gross) AS total_gross, ... COUNT(title) AS n_films, ... FROM films ... GROUP BY (release_year // 10) -- decade ... ORDER BY total_gross DESC ... ''', ... eager=True, ... ) shape: (3, 3) ┌────────┬─────────────┬─────────┐ │ decade ┆ total_gross ┆ n_films │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ u32 │ ╞════════╪═════════════╪═════════╡ │ 2000 ┆ 533316061 ┆ 1 │ │ 1990 ┆ 232338648 ┆ 3 │ │ 1970 ┆ 134821952 ┆ 1 │ └────────┴─────────────┴─────────┘ )rr=rcr>collect)rFrZrAress r,rczSQLContext.execute[s9btzz))%01!&$*?*?s{{}IcIr.c| tn t|}|jj||j|S)u Register a single frame as a table, using the given name. Parameters ---------- name Name of the table. frame eager/lazy frame to associate with this table name. See Also -------- register_globals register_many unregister Examples -------- >>> df = pl.DataFrame({"hello": ["world"]}) >>> ctx = pl.SQLContext() >>> ctx.register("frame_data", df).execute("SELECT * FROM frame_data").collect() shape: (1, 1) ┌───────┐ │ hello │ │ --- │ │ str │ ╞═══════╡ │ world │ └───────┘ )rr5r=register_ldf)rFrVr3s r,rzSQLContext.registers4> %} 2CE2J D%**- r.TrPc@t||}|j|S)u9 Register all frames (lazy or eager) found in the current globals scope. Automatically maps variable names to table names. See Also -------- register register_many unregister Parameters ---------- n Register only the most recent "n" frames. all_compatible Control whether we *also* register pandas DataFrame, Series, and pyarrow Table and RecordBatch objects. If False, only Polars classes are registered with the SQL engine. Examples -------- >>> df1 = pl.DataFrame({"a": [1, 2, 3], "b": ["x", None, "z"]}) >>> df2 = pl.DataFrame({"a": [2, 3, 4], "c": ["t", "w", "v"]}) Register frames directly from variables found in the current globals scope: >>> ctx = pl.SQLContext(register_globals=True) >>> ctx.tables() ['df1', 'df2'] Query using the register variable/frame names >>> ctx.execute( ... "SELECT a, b, c FROM df1 LEFT JOIN df2 USING (a) ORDER BY a DESC" ... ).collect() shape: (3, 3) ┌─────┬──────┬──────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪══════╪══════╡ │ 3 ┆ z ┆ w │ │ 2 ┆ null ┆ t │ │ 1 ┆ x ┆ null │ └─────┴──────┴──────┘ )r:r6)rG)r;rU)rFnr:rGs r,r@zSQLContext.register_globalss%d#.AN!!!00r.c t|xsi}|j||jD]\}}|j|||S)a Register multiple eager/lazy frames as tables, using the associated names. Parameters ---------- frames A `{name:frame, ...}` mapping. **named_frames Named eager/lazy frames, provided as kwargs. See Also -------- register register_globals unregister Examples -------- >>> lf1 = pl.LazyFrame({"a": [1, 2, 3], "b": ["m", "n", "o"]}) >>> lf2 = pl.LazyFrame({"a": [2, 3, 4], "c": ["p", "q", "r"]}) >>> lf3 = pl.LazyFrame({"a": [3, 4, 5], "b": ["s", "t", "u"]}) >>> lf4 = pl.LazyFrame({"a": [4, 5, 6], "c": ["v", "w", "x"]}) Register multiple frames at once, either by passing in as a dict... >>> ctx = pl.SQLContext().register_many({"tbl1": lf1, "tbl2": lf2}) >>> ctx.tables() ['tbl1', 'tbl2'] ...or using keyword args: >>> ctx.register_many(tbl3=lf3, tbl4=lf4).tables() ['tbl1', 'tbl2', 'tbl3', 'tbl4'] )rRrTrSr)rFrGrHrVr3s r,rUzSQLContext.register_manysKNfl# l#!<<> 'KD% MM$ & ' r.cpt|tr|g}|D]}|jj||S)a Unregister one or more eager/lazy frames by name. Parameters ---------- names Names of the tables to unregister. Notes ----- You can also control table registration lifetime by using `SQLContext` as a context manager; this can often be more useful when such control is wanted: >>> df0 = pl.DataFrame({"colx": [0, 1, 2]}) >>> df1 = pl.DataFrame({"colx": [1, 2, 3]}) >>> df2 = pl.DataFrame({"colx": [2, 3, 4]}) Frames registered in-scope are automatically unregistered on scope-exit. Note that frames registered on construction will persist through subsequent scopes. >>> # register one frame at construction time, and the other two in-scope >>> with pl.SQLContext(tbl0=df0) as ctx: ... ctx.register_many(tbl1=df1, tbl2=df2).tables() ['tbl0', 'tbl1', 'tbl2'] After scope exit, none of the tables registered in-scope remain: >>> ctx.tables() ['tbl0'] See Also -------- register register_globals register_many Examples -------- >>> df0 = pl.DataFrame({"ints": [9, 8, 7, 6, 5]}) >>> lf1 = pl.LazyFrame({"text": ["a", "b", "c"]}) >>> lf2 = pl.LazyFrame({"misc": ["testing1234"]}) Register with a SQLContext object: >>> ctx = pl.SQLContext(test1=df0, test2=lf1, test3=lf2) >>> ctx.tables() ['test1', 'test2', 'test3'] Unregister one or more of the tables: >>> ctx.unregister(["test1", "test3"]).tables() ['test2'] >>> ctx.unregister("test2").tables() [] )r&strr=rn)rFrmnms r,rnzSQLContext.unregister4s<p eS !GE &B JJ ! !" % & r.cHt|jjS)u) Return a list of the registered table names. Notes ----- The :meth:`tables` method will return the same values as the "SHOW TABLES" SQL statement, but as a list instead of a frame. Executing as SQL: >>> frame_data = pl.DataFrame({"hello": ["world"]}) >>> ctx = pl.SQLContext(hello_world=frame_data) >>> ctx.execute("SHOW TABLES", eager=True) shape: (1, 1) ┌─────────────┐ │ name │ │ --- │ │ str │ ╞═════════════╡ │ hello_world │ └─────────────┘ Calling the method: >>> ctx.tables() ['hello_world'] Examples -------- >>> df1 = pl.DataFrame({"hello": ["world"]}) >>> df2 = pl.DataFrame({"foo": ["bar", "baz"]}) >>> ctx = pl.SQLContext(hello_data=df1, foo_bar=df2) >>> ctx.tables() ['foo_bar', 'hello_data'] )sortedr= get_tablesrjs r,rizSQLContext.tablesrsHdjj++-..r.).) rFSQLContext[LazyFrame]rG/Mapping[str, CompatibleFrameType | None] | Noner@ bool | intrALiteral[False]rHCompatibleFrameType | NonereturnNone) rFSQLContext[DataFrame]rGrr@rrA Literal[True]rHrrr) rFrrGrr@rrAboolrHrrrrC) rGrr@rrArrHrrr)rZrrArrr)rZrrArrr)rZrrArrzDataFrame | LazyFrame)rzSQLContext[FrameType])rpztype[BaseException] | NonerqzBaseException | NonerrzTracebackType | Nonerr)rr)rFrrZrrArrr)rFrrZrrArrr)rFrrZrrArrr)rFrrZrrArrr)rFrrZrrArrr)rFrrZrrArrr)rZrrAz bool | NonerzLazyFrame | DataFrame)rVrr3rrr")r int | Noner:rrr")rGrrHrrr")rmzstr | Collection[str]rr")rz list[str])__name__ __module__ __qualname____doc____annotations__rrIr classmethodr[rkrsrzrcrr@rUrnrirDr.r,r$r$[sg !!''CF(+ % #?%    3  CF(+ #?%    3  CF(+ #?%    3  !!2GYOCGA'(- A'?A'% A'  A' 3 A' A'PA'F49#1 RR UU*/8989#'89 8989t  , & %    "EBE#,/;? #,/;I #,/;H BE#,/;? #,/;I #,/;H 25$$$/$ $$ 37RJRJ$/RJ RJh!H#31>B31317;31 31nCG+?+3+  +Z<|$/r.)r+rrr)r+rrr)r:rr6rr7z4str | Collection[str] | Callable[[str], bool] | Nonerzdict[str, Any])? __future__r contextlibtypingrrrpolars._dependenciesrrr r'r r(polars._typingr polars._utils.deprecationr polars._utils.pycapsuler polars._utils.unstablerpolars._utils.variousrrpolars._utils.wraprpolars.convertrrpolars.dataframerpolars.lazyframer polars.seriesrsuppress ImportError polars._plrrsyscollections.abcrrrtypesrrrrr version_infor"typing_extensionsr)r*r#r__all__r-r5r;r$rDr.r,rsO" G-.$A09H'2&& Z%)()==#55 7"*      ,,  ))C.   ((   ..   .,!BF PPP @ P  P{/#{/G))s <D66D?