{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from seeq import spy\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Logged in to <strong>http://localhost:34216/api</strong> successfully as <strong>agent_api_key</strong>.<br>Seeq Server Version: <strong>R22.0.46.08-BETA</strong><br>Seeq Python Module Version: <strong>0.46.8.159</strong></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Log into Seeq Server if you're not using Seeq Data Lab:\n",
    "spy.login(url='http://localhost:34216', credentials_file='../credentials.key', force=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# spy.search\n",
    "\n",
    "Finds signals (tags), conditions (with capsules), scalars (constants), assets or any other type of item that Seeq indexes or keeps track of.\n",
    "\n",
    "You will generally use this command before executing `spy.pull()`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`spy.search(query, all_properties=False, workbook='Data Lab >> Data Lab Analysis')`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Query Syntax\n",
    "\n",
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Path</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Humid</td><td>Example >> Cooling Tower 1</td><td>00:00:00.09</td><td>8</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ID</th>\n",
       "      <th>Path</th>\n",
       "      <th>Asset</th>\n",
       "      <th>Name</th>\n",
       "      <th>Description</th>\n",
       "      <th>Type</th>\n",
       "      <th>Value Unit Of Measure</th>\n",
       "      <th>Datasource Name</th>\n",
       "      <th>Archived</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>BA0FA2B3-29D2-43B4-86C8-A58D44297781</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area B</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>42233FDA-BCA9-44C9-A26E-FFAB86EA7AEC</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area G</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>642A67B0-AE03-4E8E-98FD-4F2A7D28B6DD</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area C</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>ABFBE527-AADC-480A-ACFA-49798B069D9D</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area J</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4207957F-BAC1-4392-80A0-0579E733CB7A</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area I</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>174CE5D8-560C-408F-93FA-11E77A21C45E</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area H</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>0641FF9A-B7A3-408A-8892-1AE57A564A29</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area A</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>285DCED1-1BDA-4A7B-9FE9-ADB5F185FD0B</td>\n",
       "      <td>Example &gt;&gt; Cooling Tower 1</td>\n",
       "      <td>Area K</td>\n",
       "      <td>Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                     ID                        Path   Asset  \\\n",
       "0  BA0FA2B3-29D2-43B4-86C8-A58D44297781  Example >> Cooling Tower 1  Area B   \n",
       "1  42233FDA-BCA9-44C9-A26E-FFAB86EA7AEC  Example >> Cooling Tower 1  Area G   \n",
       "2  642A67B0-AE03-4E8E-98FD-4F2A7D28B6DD  Example >> Cooling Tower 1  Area C   \n",
       "3  ABFBE527-AADC-480A-ACFA-49798B069D9D  Example >> Cooling Tower 1  Area J   \n",
       "4  4207957F-BAC1-4392-80A0-0579E733CB7A  Example >> Cooling Tower 1  Area I   \n",
       "5  174CE5D8-560C-408F-93FA-11E77A21C45E  Example >> Cooling Tower 1  Area H   \n",
       "6  0641FF9A-B7A3-408A-8892-1AE57A564A29  Example >> Cooling Tower 1  Area A   \n",
       "7  285DCED1-1BDA-4A7B-9FE9-ADB5F185FD0B  Example >> Cooling Tower 1  Area K   \n",
       "\n",
       "                Name  Description          Type Value Unit Of Measure  \\\n",
       "0  Relative Humidity          NaN  StoredSignal                     %   \n",
       "1  Relative Humidity          NaN  StoredSignal                     %   \n",
       "2  Relative Humidity          NaN  StoredSignal                     %   \n",
       "3  Relative Humidity          NaN  StoredSignal                     %   \n",
       "4  Relative Humidity          NaN  StoredSignal                     %   \n",
       "5  Relative Humidity          NaN  StoredSignal                     %   \n",
       "6  Relative Humidity          NaN  StoredSignal                     %   \n",
       "7  Relative Humidity          NaN  StoredSignal                     %   \n",
       "\n",
       "  Datasource Name  Archived  \n",
       "0    Example Data     False  \n",
       "1    Example Data     False  \n",
       "2    Example Data     False  \n",
       "3    Example Data     False  \n",
       "4    Example Data     False  \n",
       "5    Example Data     False  \n",
       "6    Example Data     False  \n",
       "7    Example Data     False  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "spy.search({\n",
    "    'Name': 'Humid',\n",
    "    'Path': 'Example >> Cooling Tower 1'\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This query returns anything with `Humid` in its `Name` property that also lives somewhere under `Example >> Cooling Tower 1` in an asset tree.\n",
    "\n",
    "There are several capabilities and some constraints associated with querying:\n",
    "\n",
    "1. The `Name` and `Description` properties are queried upon with the same wildcard and RegEx support as the Data tab in Seeq Workbench: https://seeq12.atlassian.net/wiki/spaces/KB/pages/146472969/Searching+for+Items\n",
    "\n",
    "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.\n",
    "\n",
    "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.\n",
    "\n",
    "4. For the `Type` property, you can specify just `Signal`, `Condition` or `Scalar` if you want to return both _stored_ and _calculated_ items.\n",
    "\n",
    "5. You can specify `Datasource Name` _or_ you can specify both `Datasource ID` and `Datasource Class` to differentiate between datasources with the same name.\n",
    "\n",
    "6. You can filter on `Data ID`, which is a unique identifier that is generally the same across instances of Seeq Server.\n",
    "\n",
    "7. You can filter on `Archived` and `Cache Enabled` using either `True` or `False` Python boolean values.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Retrieving all properties\n",
    "\n",
    "`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 this can be an expensive (slow) operation for queries that return many rows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Datasource Name</td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Example Data</td><td>Area A_*Humid*</td><td>00:00:00.04</td><td>1</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ID</th>\n",
       "      <th>Name</th>\n",
       "      <th>Description</th>\n",
       "      <th>Type</th>\n",
       "      <th>Value Unit Of Measure</th>\n",
       "      <th>Datasource Name</th>\n",
       "      <th>Archived</th>\n",
       "      <th>Scoped To</th>\n",
       "      <th>Cache Enabled</th>\n",
       "      <th>Data ID</th>\n",
       "      <th>Datasource Class</th>\n",
       "      <th>Datasource ID</th>\n",
       "      <th>Interpolation Method</th>\n",
       "      <th>Key Unit Of Measure</th>\n",
       "      <th>Maximum Interpolation</th>\n",
       "      <th>Source Maximum Interpolation</th>\n",
       "      <th>Source Value Unit Of Measure</th>\n",
       "      <th>Sync Token</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>08B8564B-EDD4-461D-B8D4-01022BE06AA6</td>\n",
       "      <td>Area A_Relative Humidity</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>%</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>NaN</td>\n",
       "      <td>True</td>\n",
       "      <td>[Tag] Area A_Relative Humidity.sim.ts.csv</td>\n",
       "      <td>Time Series CSV Files</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>Linear</td>\n",
       "      <td>ns</td>\n",
       "      <td>2min</td>\n",
       "      <td>2min</td>\n",
       "      <td>%</td>\n",
       "      <td>2020-07-21T15:15:25.060879700Z</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                     ID                      Name  \\\n",
       "0  08B8564B-EDD4-461D-B8D4-01022BE06AA6  Area A_Relative Humidity   \n",
       "\n",
       "   Description          Type Value Unit Of Measure Datasource Name  Archived  \\\n",
       "0          NaN  StoredSignal                     %    Example Data     False   \n",
       "\n",
       "   Scoped To  Cache Enabled                                    Data ID  \\\n",
       "0        NaN           True  [Tag] Area A_Relative Humidity.sim.ts.csv   \n",
       "\n",
       "        Datasource Class Datasource ID Interpolation Method  \\\n",
       "0  Time Series CSV Files  Example Data               Linear   \n",
       "\n",
       "  Key Unit Of Measure Maximum Interpolation Source Maximum Interpolation  \\\n",
       "0                  ns                  2min                         2min   \n",
       "\n",
       "  Source Value Unit Of Measure                      Sync Token  \n",
       "0                            %  2020-07-21T15:15:25.060879700Z  "
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "spy.search({\n",
    "    'Name': 'Area A_*Humid*',\n",
    "    'Datasource Name': 'Example Data'\n",
    "}, all_properties=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Estimating signal sample period\n",
    "The `estimate_sample_period` parameter adds an `Estimated Sample Period` column with a value for each signal \n",
    "returned in search query for a specified time frame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Datasource Name</td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Example Data</td><td>Area ?_Compressor Stage</td><td>00:00:05.31</td><td>11</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ID</th>\n",
       "      <th>Name</th>\n",
       "      <th>Description</th>\n",
       "      <th>Type</th>\n",
       "      <th>Value Unit Of Measure</th>\n",
       "      <th>Datasource Name</th>\n",
       "      <th>Archived</th>\n",
       "      <th>Estimated Sample Period</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2E322239-B5AD-4E49-BB8A-AD3C6FB80660</td>\n",
       "      <td>Area Z_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:00:02</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>26CA21C5-104C-4D82-8808-0E8CA9F92430</td>\n",
       "      <td>Area J_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>7470F359-F502-4768-827C-4B0C04C94364</td>\n",
       "      <td>Area G_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>0B64B51F-4D92-4E24-BCCF-5E1BB005C82C</td>\n",
       "      <td>Area B_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>BBBA3D24-2818-47A5-87C8-FC9D50A6BC7C</td>\n",
       "      <td>Area K_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>67E1DC8D-5FC0-4731-B105-1097E22F1B17</td>\n",
       "      <td>Area E_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>C31BD387-101B-419F-9D99-E15D42A39D81</td>\n",
       "      <td>Area A_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>BFB4C09D-9913-4DC1-8D6F-012602EC4422</td>\n",
       "      <td>Area D_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>0D445008-7882-4626-A480-86DC0E68CD48</td>\n",
       "      <td>Area H_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>114808AF-5AFF-41FA-ABBA-45AE564BA562</td>\n",
       "      <td>Area C_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>132EFE94-58EC-4453-87B0-8C2239699608</td>\n",
       "      <td>Area I_Compressor Stage</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>string</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "      <td>00:02:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                      ID                     Name  \\\n",
       "0   2E322239-B5AD-4E49-BB8A-AD3C6FB80660  Area Z_Compressor Stage   \n",
       "1   26CA21C5-104C-4D82-8808-0E8CA9F92430  Area J_Compressor Stage   \n",
       "2   7470F359-F502-4768-827C-4B0C04C94364  Area G_Compressor Stage   \n",
       "3   0B64B51F-4D92-4E24-BCCF-5E1BB005C82C  Area B_Compressor Stage   \n",
       "4   BBBA3D24-2818-47A5-87C8-FC9D50A6BC7C  Area K_Compressor Stage   \n",
       "5   67E1DC8D-5FC0-4731-B105-1097E22F1B17  Area E_Compressor Stage   \n",
       "6   C31BD387-101B-419F-9D99-E15D42A39D81  Area A_Compressor Stage   \n",
       "7   BFB4C09D-9913-4DC1-8D6F-012602EC4422  Area D_Compressor Stage   \n",
       "8   0D445008-7882-4626-A480-86DC0E68CD48  Area H_Compressor Stage   \n",
       "9   114808AF-5AFF-41FA-ABBA-45AE564BA562  Area C_Compressor Stage   \n",
       "10  132EFE94-58EC-4453-87B0-8C2239699608  Area I_Compressor Stage   \n",
       "\n",
       "    Description          Type Value Unit Of Measure Datasource Name  Archived  \\\n",
       "0           NaN  StoredSignal                string    Example Data     False   \n",
       "1           NaN  StoredSignal                string    Example Data     False   \n",
       "2           NaN  StoredSignal                string    Example Data     False   \n",
       "3           NaN  StoredSignal                string    Example Data     False   \n",
       "4           NaN  StoredSignal                string    Example Data     False   \n",
       "5           NaN  StoredSignal                string    Example Data     False   \n",
       "6           NaN  StoredSignal                string    Example Data     False   \n",
       "7           NaN  StoredSignal                string    Example Data     False   \n",
       "8           NaN  StoredSignal                string    Example Data     False   \n",
       "9           NaN  StoredSignal                string    Example Data     False   \n",
       "10          NaN  StoredSignal                string    Example Data     False   \n",
       "\n",
       "   Estimated Sample Period  \n",
       "0                 00:00:02  \n",
       "1                 00:02:00  \n",
       "2                 00:02:00  \n",
       "3                 00:02:00  \n",
       "4                 00:02:00  \n",
       "5                 00:02:00  \n",
       "6                 00:02:00  \n",
       "7                 00:02:00  \n",
       "8                 00:02:00  \n",
       "9                 00:02:00  \n",
       "10                00:02:00  "
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "spy.search({\n",
    "    'Name': 'Area ?_Compressor Stage',\n",
    "    'Datasource Name': 'Example Data'\n",
    "}, estimate_sample_period=dict(Start='2019-01-01', End='2019-01-30'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Workbook scoping\n",
    "\n",
    "The `workbook=<workbook_path>` 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.\n",
    "\n",
    "If you want to only return globally-scoped items, specify `workbook=None` as the argument.\n",
    "\n",
    "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)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DataFrame as input\n",
    "\n",
    "Instead of a Python dictionary for the `query` parameter, you can supply a Pandas DataFrame.\n",
    "\n",
    "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.\n",
    "\n",
    "The column headers specify the properties to search on and the column values specify the match criteria.\n",
    "\n",
    "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`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Name</th>\n",
       "      <th>Datasource Name</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Area A_Temperature</td>\n",
       "      <td>Example Data</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Area B_Compressor Power</td>\n",
       "      <td>Example Data</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Optimize</td>\n",
       "      <td>Example Data</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                      Name Datasource Name\n",
       "0       Area A_Temperature    Example Data\n",
       "1  Area B_Compressor Power    Example Data\n",
       "2                 Optimize    Example Data"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_items = pd.DataFrame({\n",
    "    'Name': [\n",
    "        'Area A_Temperature',\n",
    "        'Area B_Compressor Power',\n",
    "        'Optimize'\n",
    "    ],\n",
    "    'Datasource Name': 'Example Data'\n",
    "})\n",
    "\n",
    "my_items"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Datasource Name</td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Example Data</td><td>Area A_Temperature</td><td>00:00:00.03</td><td>1</td><td>Success</td></tr><tr style=\"background-color: #EEFFEE;\"><td>1</td><td>Example Data</td><td>Area B_Compressor Power</td><td>00:00:00.01</td><td>1</td><td>Success</td></tr><tr style=\"background-color: #EEFFEE;\"><td>2</td><td>Example Data</td><td>Optimize</td><td>00:00:00.01</td><td>0</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ID</th>\n",
       "      <th>Name</th>\n",
       "      <th>Description</th>\n",
       "      <th>Type</th>\n",
       "      <th>Value Unit Of Measure</th>\n",
       "      <th>Datasource Name</th>\n",
       "      <th>Archived</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0181190A-01B7-4720-9ED4-C54FC6A7E696</td>\n",
       "      <td>Area A_Temperature</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>°F</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>F0C9C217-C0CF-4D10-BF02-A213C9FB4AC1</td>\n",
       "      <td>Area B_Compressor Power</td>\n",
       "      <td>NaN</td>\n",
       "      <td>StoredSignal</td>\n",
       "      <td>kW</td>\n",
       "      <td>Example Data</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                     ID                     Name  Description  \\\n",
       "0  0181190A-01B7-4720-9ED4-C54FC6A7E696       Area A_Temperature          NaN   \n",
       "1  F0C9C217-C0CF-4D10-BF02-A213C9FB4AC1  Area B_Compressor Power          NaN   \n",
       "\n",
       "           Type Value Unit Of Measure Datasource Name  Archived  \n",
       "0  StoredSignal                    °F    Example Data     False  \n",
       "1  StoredSignal                    kW    Example Data     False  "
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "spy.search(my_items)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that there are no results with `Optimize` in the name because it does not exactly match any items."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Workbench Analysis URL as input\n",
    "Alternatively, you can supply the URL of a Workbench Analysis worksheet to the `query` parameter. The URL must be \n",
    "provided as a `str`.\n",
    "\n",
    "This is generally useful when you already have an Analysis worksheet loaded with signals, scalars or conditions \n",
    "and want to programmatically know what is loaded in that particular worksheet from Seeq Data Lab. A common scenario is \n",
    "that you want to pull all signals or conditions from a worksheet into the Data Lab notebook but you want to see first \n",
    "how many or which signals and conditions are loaded in that worksheet. \n",
    "\n",
    "`worksheet_url = 'http://localhost:34216/workbook/<workbookID>/worksheet/<worksheetID>'`\n",
    "\n",
    "`spy.search(worksheet_url)`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Properties stored in the output DataFrame\n",
    "If you assigned the results of `spy.search()` to a variable you can also access properties stored in the DataFrame \n",
    "that contain metadata of the `spy.search()` function call. \n",
    "\n",
    "One scenario where this is useful is for expensive searches that take a long time to complete.\n",
    "In that case, it is common to pickle the resulting DataFrame for later use. Knowing what values for input parameters \n",
    "were used to obtain that pickled DataFrame can then be helpful when it is re-used. \n",
    "\n",
    "The properties stored in the output DataFrame of `spy.search()` are\n",
    "\n",
    "\n",
    "Property         |   Description\n",
    "-----------------|---------------------------------------------------------------------------------------------------\n",
    "func             |   A str value of 'spy.search'\n",
    "kwargs           |   A dict with the values of the input parameters passed to spy.search to get the output DataFrame \n",
    "status           | A spy.Status object with the status of the spy.search call\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Datasource Name</td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Example Data</td><td>Area ?_Compressor Stage</td><td>00:00:00.78</td><td>11</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "my_items = spy.search({\n",
    "    'Name': 'Area ?_Compressor Stage',\n",
    "    'Datasource Name': 'Example Data'\n",
    "}, estimate_sample_period=dict(Start='2019-01-01', End='2019-01-30'))\n",
    "my_items.to_pickle('pickled_search.pkl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "To know what function generated this DataFrame use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "pycharm": {
     "name": "#%% \n"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spy.search'"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "unpickled_search = pd.read_pickle('pickled_search.pkl')\n",
    "unpickled_search.func"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "To access the values of input parameters passed to `spy.search`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'query': {'Name': 'Area ?_Compressor Stage'},\n",
       " 'all_properties': False,\n",
       " 'workbook': 'Data Lab >> Data Lab Analysis',\n",
       " 'recursive': True,\n",
       " 'include_archived': False,\n",
       " 'estimate_sample_period': {'Start': '2019-01-01', 'End': '2019-01-30'},\n",
       " 'quiet': False,\n",
       " 'status': None}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "unpickled_search.kwargs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "You can even recycle the kwargs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"background-color: #EEFFEE;text-align: left;\">Query successful</div><table><tr><td style=\"background-color: #EEFFEE;\"></td><td style=\"background-color: #EEFFEE;\">Name</td><td style=\"background-color: #EEFFEE;\">Time</td><td style=\"background-color: #EEFFEE;\">Count</td><td style=\"background-color: #EEFFEE;\">Result</td></tr><tr style=\"background-color: #EEFFEE;\"><td>0</td><td>Area ?_Compressor Stage</td><td>00:00:00.25</td><td>11</td><td>Success</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "my_items_again = spy.search(**unpickled_search.kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "To access the `spy.status` object use `unpickled_search.status`. For example, if you want to know what queries were \n",
    "successful and what queries failed, access the status DataFrame with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "pycharm": {
     "name": "#%% \n"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Datasource Name</th>\n",
       "      <th>Name</th>\n",
       "      <th>Time</th>\n",
       "      <th>Count</th>\n",
       "      <th>Result</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Example Data</td>\n",
       "      <td>Area ?_Compressor Stage</td>\n",
       "      <td>0:00:00.778813</td>\n",
       "      <td>11</td>\n",
       "      <td>Success</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Datasource Name                     Name            Time  Count   Result\n",
       "0    Example Data  Area ?_Compressor Stage  0:00:00.778813     11  Success"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "unpickled_search.status.df"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "pycharm": {
   "stem_cell": {
    "cell_type": "raw",
    "metadata": {
     "collapsed": false
    },
    "source": []
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
