.. code:: ipython3 from seeq import spy import pandas as pd # Set the compatibility option so that you maximize the chance that SPy will remain compatible with your notebook/script spy.options.compatibility = 192 .. code:: ipython3 # Log into Seeq Server if you're not using Seeq Data Lab: spy.login(url='http://localhost:34216', credentials_file='../credentials.key', force=False) spy.search ========== Finds signals (tags), conditions (with capsules), scalars (constants), assets or any other type of item that Seeq indexes or keeps track of. You will generally use this command before executing ``spy.pull()``. ``spy.search(query, all_properties=False, workbook='Data Lab >> Data Lab Analysis')`` Query Syntax ------------ The ``query`` parameter is a dictionary of ``'Property': 'Filter'`` values that are applied using AND logic by Seeq Server. Let’s use the following examples to illustrate the important parts: .. code:: ipython3 spy.search({ 'Name': 'Humid', 'Path': 'Example >> Cooling Tower 1' }) This query returns anything with ``Humid`` in its ``Name`` property that also lives somewhere under ``Example >> Cooling Tower 1`` in an asset tree. There are several capabilities and some constraints associated with querying: 1. The ``Name`` and ``Description`` properties are queried upon with the `same wildcard and RegEx support as the Data tab in Seeq Workbench `__. 2. The ``Path`` property is a *virtual* property that specifies the path through an asset tree from its root, with ``>>`` as delimiters for each level in the asset tree. 3. The returned ``Asset`` property is just the leaf asset node in the tree. It can only be used in tandem with the ``Path`` property. 4. For the ``Type`` property, you can specify just ``Signal``, ``Condition`` or ``Scalar`` if you want to return both *stored* and *calculated* items. 5. You can specify ``Datasource Name`` *or* you can specify both ``Datasource ID`` and ``Datasource Class`` to differentiate between datasources with the same name. 6. You can filter on ``Data ID``, which is a unique identifier that is generally the same across instances of Seeq Server. 7. You can filter on ``Archived`` and ``Cache Enabled`` using either ``True`` or ``False`` Python boolean values. Retrieving all properties ------------------------- ``spy.search()`` only returns a subset of item properties as can be seen in the output above. If you want to retrieve all properties, use ``all_properties=True``. Note that when interfacing with Seeq Server version R61 and earlier, this can be an expensive (slow) operation for queries that return many rows. In R62 and later, this query has been optimized to be much faster. .. code:: ipython3 spy.search({ 'Name': 'Area A_*Humid*', 'Datasource Name': 'Example Data' }, all_properties=True) You can also use the ``include_properties=['Property Name 1', 'Property Name 2']`` argument if you want to explicitly return certain properties. Estimating signal sample period ------------------------------- The ``estimate_sample_period`` parameter adds an ``Estimated Sample Period`` column with a value for each signal returned in search query for a specified time frame. This period is calculated using the ``estimateSamplePeriod()`` Formula function. .. code:: ipython3 spy.search({ 'Name': 'Area ?_Compressor Stage', 'Datasource Name': 'Example Data' }, estimate_sample_period=dict(Start='2019-01-01', End='2019-01-30')) Workbook scoping ---------------- The ``workbook=`` parameter allows you to include items in your results that are scoped to a particular workbook. If you exclude the argument, then by default your search results will include both globally-scoped items and workbook-scoped items from the **Data Lab >> Data Lab Analysis** workbook (folder path delimiter by ``>>``, workbook name at the end). This workbook generally will only exist if you have previous called ``spy.push()``. This default behavior forces your ``spy.push()`` and subsequent ``spy.search()`` activities to be *sandboxed*, meaning that they will only be visible to you within a particular workbook. If you want all items regardless of scope, specify ``workbook=spy.GLOBALS_AND_ALL_WORKBOOKS``. If you want only globally-scoped items, specify ``workbook=spy.GLOBALS_ONLY``. Another option is to specify ``Scoped To`` within your query block. You must supply a Workbook ID – not a workbook path like the ``workbook`` parameter. This approach will limit your search to just those items scoped to a particular workbook (it will *exclude* globally-scoped items). DataFrame as input ------------------ Instead of a Python dictionary for the ``query`` parameter, you can supply a Pandas DataFrame. This is generally useful when you have a DataFrame full of tag names but don’t know the Seeq ``ID`` value and therefore can’t retrieve data via ``spy.pull()``. Calling ``spy.search(data_frame)`` effectively “fills in” the ``ID`` field for you wherever possible. The column headers specify the properties to search on and the column values specify the match criteria. If you don’t specify wildcards or use a RegEx, the match must be exact. (This behavior is in contrast to the dictionary case, where the non-wildcard/RegEx match is a “contains” comparison.) It is assumed that your DataFrame property values should match exactly so that you can have a large set of items to query for and there won’t be ambiguity between item names like ``F1843CC`` and ``F1843CC.SP``. .. code:: ipython3 my_items = pd.DataFrame({ 'Name': [ 'Area A_Temperature', 'Area B_Compressor Power', 'Optimize' ], 'Datasource Name': 'Example Data' }) my_items .. code:: ipython3 spy.search(my_items) Notice that there are no results with ``Optimize`` in the name because it does not exactly match any items. Workbench Analysis URL as input ------------------------------- Alternatively, you can supply the URL of a Workbench Analysis worksheet to the ``query`` parameter. The URL must be provided as a ``str``. This is generally useful when you already have an Analysis worksheet loaded with signals, scalars or conditions and want to programmatically know what is loaded in that particular worksheet from Seeq Data Lab. A common scenario is that you want to pull all signals or conditions from a worksheet into the Data Lab notebook but you want to see first how many or which signals and conditions are loaded in that worksheet. :: spy.search('http://localhost:34216/workbook//worksheet/') Pickling -------- Sometimes a search is “expensive” and takes a long time to complete. In that case, it is common to “pickle” the resulting DataFrame for later use, like so: .. code:: ipython3 my_items = spy.search({ 'Name': 'Area ?_Compressor Stage', 'Datasource Name': 'Example Data' }, estimate_sample_period=dict(Start='2019-01-01', End='2019-01-30')) my_items.to_pickle('pickled_search.pkl') Now you can “unpickle” the DataFrame and use it for a pull without incurring the cost of re-executing the search: .. code:: ipython3 unpickled_search = pd.read_pickle('pickled_search.pkl') You can access some of the original context of the search via the ``spy`` attribute of the unpickled DataFrame. For example, the ``spy.status`` tells you what queries were successful and what queries failed. .. code:: ipython3 unpickled_search.spy.status.df Detailed Help ------------- All SPy functions have detailed documentation to help you use them. Just execute ``help(spy.)`` like you see below. .. code:: ipython3 help(spy.search) API Reference Links ------------------- - :py:func:`seeq.spy.search`