Add list_orphaned_database_entities service (#752)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

custom_components/spook/ectoplasms/homeassistant/services/list_orphaned_database_entities.py

@@ -0,0 +1,47 @@
+"""Spook - Your homie."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import create_engine, text
+
+from homeassistant.components.homeassistant import DOMAIN
+from homeassistant.components.recorder import (
+    get_instance,
+)
+from homeassistant.core import ServiceResponse, SupportsResponse
+
+from ....services import AbstractSpookService
+
+if TYPE_CHECKING:
+    from homeassistant.core import ServiceCall
+
+
+class SpookService(AbstractSpookService):
+    """Home Assistant Core integration service to list all orphaned database entities."""
+
+    domain = DOMAIN
+    service = "list_orphaned_database_entities"
+    supports_response = SupportsResponse.ONLY
+
+    async def async_handle_service(self, call: ServiceCall) -> ServiceResponse:
+        """Handle the service call."""
+        query = text(
+            """
+            SELECT DISTINCT(entity_id) FROM states_meta
+            """
+        )
+        db_url = get_instance(self.hass).db_url
+        engine = create_engine(db_url)
+        with engine.connect() as conn:
+            response = conn.execute(query)
+            db_list = [e[0] for e in response]
+        states_list = self.hass.states.async_entity_ids()
+        compared_list = set(db_list).difference(states_list)
+        if call.return_response:
+            return {
+                "count": len(compared_list),
+                "entities": list(compared_list),
+            }
+        return None

custom_components/spook/services.yaml

@@ -703,6 +703,11 @@ homeassistant_delete_all_orphaned_entities:
     integration is offline or not working since Home Assistant started. Calling
     this service will delete those entities as well.
 
+homeassistant_list_orphaned_database_entities:
+  name: List all orphaned database entities 👻
+  description: >-
+    Lists all orphaned database entities unclaimed by any integration.
+
 homeassistant_restart:
   name: Restart 👻
   description: Restart the Home Assistant service.

documentation/core_extensions.md

@@ -26,7 +26,7 @@ Programmatically enable/disable any device in Home Assistant using service calls
 :::{card} Entity management
 :footer: 📚 [Learn more](entities.md)
 
-Automate controlling your entities using services. Hide/unhide, enable/disable, and even delete all orphaned entities all at one go.
+Automate entity control with services: hide/unhide, enable/disable, list, and delete orphaned (database) entities.
 
 :::
 

documentation/entities.md

@@ -366,6 +366,76 @@ service: homeassistant.delete_all_orphaned_entities
 
 :::
 
+### List all orphaned database entities
+
+Mass clean up your database with the help of Spook by listing all orphaned database entities in one service call.
+
+Orphaned database entities are entities that are no longer claimed by integration but still exist in the database. This can happen when an integration is removed or when an entity is disabled.
+
+```{figure} ./images/entities/list_orphaned_database_entities.png
+:alt: Screenshot of the Home Assistant list orphaned database entities service call in the developer tools.
+:align: center
+```
+
+```{list-table}
+:header-rows: 1
+* - Service properties
+* - {term}`Service`
+  - List orphaned database entities 👻
+* - {term}`Service name`
+  - `homeassistant.list_orphaned_database_entities`
+* - {term}`Service targets`
+  - No
+* - {term}`Service response`
+  - Service response
+* - {term}`Spook's influence <influence of spook>`
+  - Newly added service.
+* - {term}`Developer tools`
+  - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.list_orphaned_database_entities)
+    [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=homeassistant.list_orphaned_database_entities)
+```
+
+```{list-table}
+:header-rows: 2
+* - Service response data
+* - Attribute
+  - Type
+* - `count`
+  - {term}`integer <integer>`
+* - `entities`
+  - {term}`list <list>`
+```
+
+:::{seealso} Example {term}`service call <service call>` in {term}`YAML`
+:class: dropdown
+
+```{code-block} yaml
+:linenos:
+service: homeassistant.list_orphaned_database_entities
+```
+
+:::
+
+:::{tip} Script to remove entities from database
+:class: dropdown
+
+```yaml
+alias: Delete orphaned database entities
+sequence:
+  - service: homeassistant.list_orphaned_database_entities
+    response_variable: orphaned
+  - service: recorder.purge_entities
+    target:
+      entity_id: |
+        {{ orphaned.entities }}
+    data:
+      keep_days: 0
+mode: single
+```
+
+That template will find the area ID of the area with the name "Living room".
+:::
+
 ## Blueprints & tutorials
 
 There are currently no known {term}`blueprints <blueprint>` or tutorials for the enhancements Spook provides for these features. If you created one or stumbled upon one, [please let us know in our discussion forums](https://github.com/frenck/spook/discussions).