{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d522df84",
   "metadata": {},
   "source": [
    "# Configure database-specific options"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a425a60",
   "metadata": {},
   "source": [
    "Granta MI BoM Analytics work with an off-the-shelf Granta MI Restricted Substances database. However, there are\n",
    "some situations in which additional run-time configuration changes are required:\n",
    "\n",
    "- If the database key or table names have been modified from their default values, these must be set on the\n",
    "  ``Connection`` object.\n",
    "- If the number of linked records is very large, the batch sizes should be changed for each query. For more\n",
    "  information, see [Batching requests](../../user_guide/batching.rst)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47022c11",
   "metadata": {},
   "source": [
    "## Specify a custom database key or table name"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f251b24d",
   "metadata": {},
   "source": [
    "The default database key, ``MI_Restricted_Substances``, is used if no database key is specified. To specify a\n",
    "key, use the ``Connection.set_database_details()`` method. The specified key is then used for all queries made\n",
    "with this ``Connection`` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd631f73",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.bomanalytics import Connection\n",
    "\n",
    "server_url = \"http://my_grantami_server/mi_servicelayer\"\n",
    "cxn = Connection(server_url).with_credentials(\"user_name\", \"password\").connect()\n",
    "cxn.set_database_details(database_key=\"ACME_SUBSTANCES_DATABASE\")\n",
    "cxn"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef39c4d4",
   "metadata": {},
   "source": [
    "It is also possible to specify alternative names for the relevant restricted substances tables if they\n",
    "have been modified from the defaults. You provide the names to the ``.set_database_details()`` method in the same way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2d27cede",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "cxn.set_database_details(in_house_materials_table_name=\"ACME Materials\")\n",
    "cxn"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcf0bfbf",
   "metadata": {},
   "source": [
    "## Change batch size"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a1af71d",
   "metadata": {},
   "source": [
    "The queries that can be performed with this package are batched if they exceed a certain size. This is achieved by\n",
    "splitting the list of parts, materials, and so on into smaller lists to reduce the overall time taken\n",
    "to perform the query. Default batch sizes have been chosen based on typical tabular attribute sizes, but\n",
    "these might need to be changed in some situations. For examples, see the relevant page in the API documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99aeaec6",
   "metadata": {},
   "source": [
    "The batch size is included in the query ``__repr__``. The following cell shows a ``SpecificationComplianceQuery``\n",
    "object with the default batch size."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc21d171",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.bomanalytics import queries\n",
    "\n",
    "spec_query = queries.SpecificationComplianceQuery()\n",
    "spec_query"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96a9b47a",
   "metadata": {},
   "source": [
    "You can manually set the batch size like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eab806b8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "spec_query = spec_query.with_batch_size(5)\n",
    "spec_query"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a70628e",
   "metadata": {},
   "source": [
    "## Set depth of specification-to-specification links"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1af1e98a",
   "metadata": {},
   "source": [
    "> Supported with Restricted Substances Reports 2023 R2 and later"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "198a9ee3",
   "metadata": {},
   "source": [
    "The Restricted Substances database allows Specification records to be defined in terms of other Specification records.\n",
    "Since this is a recursive relationship, there is in principle no limit to the complexity of these\n",
    "specification-to-specification (spec-to-spec) hierarchies. By default, this package considers every spec-to-spec\n",
    "hierarchy completely, with no truncation imposed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c202f63c",
   "metadata": {},
   "source": [
    "For typical databases this is the correct and desired behavior. However, in some circumstances, this may cause query\n",
    "times and response sizes to become very large. In such cases, you should control the maximum spec-to-spec hierarchy\n",
    "depth followed using the ``maximum_spec_link_depth`` parameter on the ``BomAnalyticsClient`` object."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da707ae9",
   "metadata": {},
   "source": [
    "The default value is ``None``. Setting it to a positive integer limits the depth to at most that many spec-to-spec\n",
    "links."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9df83f7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "cxn.maximum_spec_link_depth = 2\n",
    "cxn"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "formats": "ipynb,py:light"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}