foundryts.search.Search¶

class foundryts.search.Search¶

Interface for performing search queries on timeseries using the Ontology.

This interface enables searching a collection of time series using properties in the Ontology. The search can be refined with granular filters to determine which objects to include in the search.

This is useful for querying multiple timeseries when programmatic access to the time series is dynamic and based property values of the ontology. Consider the example below:

Your Ontology contains a stock object type with properties [ticker, sector, exchange, price]. To get the price for all stocks in the “Technology” sector, you can use Search.series() with the following query:

>>> fts = FoundryTS()
>>> tech_stocks_price = fts.search.series(
...     query=(ontology("sector") == "Technology"),
...     object_types=["stock"],
...     property_type_id="price"
... )
>>> tech_stocks_price.to_pandas()
           series               timestamp   value
    0     stock-A 2023-01-01 00:00:00.000  150.75
    1     stock-A 2023-01-02 00:00:00.000  152.30
    2     stock-A 2023-01-03 00:00:00.000  148.90
    3     stock-B 2023-01-01 00:00:00.000  200.50
    4     stock-B 2023-01-02 00:00:00.000  202.75
    5     stock-B 2023-01-03 00:00:00.000  198.40
    6     stock-C 2023-01-01 00:00:00.000  120.10
    7     stock-C 2023-01-02 00:00:00.000  118.95
    8     stock-C 2023-01-03 00:00:00.000  121.70
    9     stock-D 2023-01-01 00:00:00.000  310.20
    10    stock-D 2023-01-02 00:00:00.000  312.50
    11    stock-D 2023-01-03 00:00:00.000  308.90

Similarly, you can search for stocks in a specific exchange or using other relevant properties of your object type.

Search methods are accessible via the FoundryTS.search singleton property as shown in the example above.

:::callout{theme="warning" title="Note"} Search can only query timeseries references and not values within the timeseries themselves (for example searching for series or points where values satisfy a predicate). For searching data within timeseries see dsl() and time_series_search(). :::

abstract series(query, max_results=10000, **kwargs)¶

Searches for timeseries using the passed query and returns a NodeCollection containing all results.

The search syntax checks equality against properties in the Ontology using ontology() using the == operator. Additionally, you can scope the search to specific object types in the Ontology using object_types. This is recommended to avoid searching over the entire Ontology.

Parameters:
query (Any) – Search query composed of operators and operands above.
max_results (int , optional) – Maximum number of series definition results to return between 1 and 10,000 results (default is 10,000).
**kwargs – Options and flags for additional search behavior behavior.
Keyword Arguments:
object_types (List [str ] , optional) – Ontology objects with time series properties to search in the query (default is to search over all time series objects).
property_type_id (str , optional) – Time series property in the object to return, this is required if an object contains multiple time series properties (TSPs) and no default TSP is set. ↗ Default TSPs can be defined for any object with TSPs in the platform.
experimental_enable_complex_properties (bool , optional) – Whether to send Time Series Properties (TSPs) to the time series backend. This is required when using non-primitive time dependent properties such as ↗ Templates or for time series properties backed by multiple time series syncs (such time series are written into the Ontology as ↗ Qualified series ID) (default is False).
Returns: A NodeCollection containing all time series references that match the search query as FunctionNode.
Return type: NodeCollection

:::callout{theme="warning" title="Note"} Ensure that properties that you use in your query (with ontology()) are searchable or search will fail. Time series properties are not searchable.

The experimental_enable_complex_properties flag is required when using non-primitive time dependent properties such as Templates or multi-sync properties. :::

Examples¶

>>> fts = FoundryTS()

>>> tsp_search_without_query = fts.search.series(object_types=["stock-series"])
>>> tsp_search_without_query.to_pandas()
       series               timestamp  value
0    SPX_open 1970-01-01 00:00:00.000    1.5
1    SPX_open 1970-01-01 00:00:00.001    2.5
2    SPX_open 1970-01-01 00:00:00.004    3.5
3  ZVZZT_open 1970-01-01 00:00:00.000    2.5
4  ZVZZT_open 1970-01-01 00:00:00.001    3.5
5  ZVZZT_open 1970-01-01 00:00:00.004    4.5

>>> tsp_search = fts.search.series((search.ontology("ticker") == "SPX"))
>>> tsp_search.to_pandas()
      series               timestamp  value
0   SPX_open 1970-01-01 00:00:00.000    1.5
1   SPX_open 1970-01-01 00:00:00.001    2.5
2   SPX_open 1970-01-01 00:00:00.004    3.5
3  SPX_close 1970-01-01 00:00:00.005   15.0
4  SPX_close 1970-01-01 00:00:00.006   25.0
5  SPX_close 1970-01-01 00:00:00.007   35.0

>>> tsp_search_with_experimental_properties = fts.search.series(
...     (search.ontology("ticker") == "SPX"),
...     object_types=["stock-series"],
...     experimental_enable_complex_properties=True,
... )
>>> tsp_search_with_experimental_properties.to_pandas()
                        series               timestamp  value
0  stock-series:SPX:open_price 1970-01-01 00:00:00.000    1.5
1  stock-series:SPX:open_price 1970-01-01 00:00:00.001    2.5
2  stock-series:SPX:open_price 1970-01-01 00:00:00.004    3.5

中文翻译¶

foundryts.search.Search¶

class foundryts.search.Search¶

用于通过本体（Ontology）对时间序列执行搜索查询的接口。

该接口支持利用本体中的属性搜索时间序列集合。可通过精细过滤器来限定搜索范围，确定要纳入搜索的对象。

当需要以编程方式动态访问时间序列，且访问逻辑基于本体的属性值时，该接口对于查询多个时间序列非常有用。请参考以下示例：

您的本体包含一个 stock 对象类型，其属性为 [ticker, sector, exchange, price]。要获取"Technology"板块所有股票的价格，可以使用 Search.series() 并执行以下查询：

>>> fts = FoundryTS()
>>> tech_stocks_price = fts.search.series(
...     query=(ontology("sector") == "Technology"),
...     object_types=["stock"],
...     property_type_id="price"
... )
>>> tech_stocks_price.to_pandas()
           series               timestamp   value
    0     stock-A 2023-01-01 00:00:00.000  150.75
    1     stock-A 2023-01-02 00:00:00.000  152.30
    2     stock-A 2023-01-03 00:00:00.000  148.90
    3     stock-B 2023-01-01 00:00:00.000  200.50
    4     stock-B 2023-01-02 00:00:00.000  202.75
    5     stock-B 2023-01-03 00:00:00.000  198.40
    6     stock-C 2023-01-01 00:00:00.000  120.10
    7     stock-C 2023-01-02 00:00:00.000  118.95
    8     stock-C 2023-01-03 00:00:00.000  121.70
    9     stock-D 2023-01-01 00:00:00.000  310.20
    10    stock-D 2023-01-02 00:00:00.000  312.50
    11    stock-D 2023-01-03 00:00:00.000  308.90

类似地，您也可以搜索特定交易所的股票，或使用对象类型的其他相关属性进行搜索。

如上例所示，可通过 FoundryTS.search 单例属性访问搜索方法。

:::callout{theme="warning" title="注意"} 搜索功能只能查询时间序列引用，不能查询时间序列本身的值（例如，搜索满足某个谓词值的序列或数据点）。如需搜索时间序列内的数据，请参阅 dsl() 和 time_series_search()。 :::

abstract series(query, max_results=10000, **kwargs)¶

使用传入的查询搜索时间序列，并返回包含所有结果的 NodeCollection。

搜索语法通过 ontology() 使用 == 运算符检查本体中属性的相等性。此外，您可以使用 object_types 将搜索范围限定在本体中的特定对象类型。建议这样做，以避免搜索整个本体。

参数：
query (Any) – 由上述运算符和操作数组成的搜索查询。
max_results (int , 可选) – 返回的序列定义结果的最大数量，范围为 1 到 10,000 条结果（默认值为 10,000）。
**kwargs – 用于额外搜索行为的选项和标志。
关键字参数：
object_types (List [str ] , 可选) – 查询中要搜索的具有时间序列属性的本体对象（默认搜索所有时间序列对象）。
property_type_id (str , 可选) – 要返回的对象中的时间序列属性。如果对象包含多个时间序列属性（TSP）且未设置默认 TSP，则需要指定此参数。↗ 可在平台上为任何包含 TSP 的对象定义默认 TSP。
experimental_enable_complex_properties (bool , 可选) – 是否将时间序列属性（TSP）发送到时间序列后端。当使用非原始时间依赖属性（如 ↗ 模板）或由多个时间序列同步支持的时间序列属性（此类时间序列作为 ↗ 限定序列 ID 写入本体）时需要此参数（默认值为 False）。
返回： 一个 NodeCollection，包含所有匹配搜索查询的时间序列引用，以 FunctionNode 形式呈现。
返回类型： NodeCollection

:::callout{theme="warning" title="注意"} 请确保查询中使用的属性（通过 ontology()）是可搜索的，否则搜索将失败。时间序列属性不可搜索。

当使用非原始时间依赖属性（如模板或多同步属性）时，需要设置 experimental_enable_complex_properties 标志。 :::

示例¶

>>> fts = FoundryTS()

>>> tsp_search_without_query = fts.search.series(object_types=["stock-series"])
>>> tsp_search_without_query.to_pandas()
       series               timestamp  value
0    SPX_open 1970-01-01 00:00:00.000    1.5
1    SPX_open 1970-01-01 00:00:00.001    2.5
2    SPX_open 1970-01-01 00:00:00.004    3.5
3  ZVZZT_open 1970-01-01 00:00:00.000    2.5
4  ZVZZT_open 1970-01-01 00:00:00.001    3.5
5  ZVZZT_open 1970-01-01 00:00:00.004    4.5

>>> tsp_search = fts.search.series((search.ontology("ticker") == "SPX"))
>>> tsp_search.to_pandas()
      series               timestamp  value
0   SPX_open 1970-01-01 00:00:00.000    1.5
1   SPX_open 1970-01-01 00:00:00.001    2.5
2   SPX_open 1970-01-01 00:00:00.004    3.5
3  SPX_close 1970-01-01 00:00:00.005   15.0
4  SPX_close 1970-01-01 00:00:00.006   25.0
5  SPX_close 1970-01-01 00:00:00.007   35.0

>>> tsp_search_with_experimental_properties = fts.search.series(
...     (search.ontology("ticker") == "SPX"),
...     object_types=["stock-series"],
...     experimental_enable_complex_properties=True,
... )
>>> tsp_search_with_experimental_properties.to_pandas()
                        series               timestamp  value
0  stock-series:SPX:open_price 1970-01-01 00:00:00.000    1.5
1  stock-series:SPX:open_price 1970-01-01 00:00:00.001    2.5
2  stock-series:SPX:open_price 1970-01-01 00:00:00.004    3.5