ds_protocol_graphql_py_lib.dataset.graphql ========================================== .. py:module:: ds_protocol_graphql_py_lib.dataset.graphql .. autoapi-nested-parse:: **File:** ``graphql.py`` **Region:** ``ds_protocol_graphql_py_lib/dataset`` GraphQL dataset implementation for CRUD operations via GraphQL API. .. rubric:: Example >>> linked_service = HttpLinkedService( ... settings=HttpLinkedServiceSettings( ... host="https://api.example.graphql/graphql", ... auth_type=AuthType.NO_AUTH, ... ), ... id="service-id", ... name="graphql_service", ... version="1.0.0", ... ) >>> dataset = GraphqlDataset( ... linked_service=linked_service, ... settings=GraphqlDatasetSettings( ... url="https://api.example.graphql/graphql", ... read=GraphqlReadSettings( ... query="{ users { id name email } }" ... ), ... ), ... id="dataset-id", ... name="graphql_dataset", ... version="1.0.0", ... ) >>> dataset.read() Attributes ---------- .. autoapisummary:: ds_protocol_graphql_py_lib.dataset.graphql.logger ds_protocol_graphql_py_lib.dataset.graphql.GraphqlDatasetSettingsType Classes ------- .. autoapisummary:: ds_protocol_graphql_py_lib.dataset.graphql.GraphqlReadSettings ds_protocol_graphql_py_lib.dataset.graphql.GraphqlDeleteSettings ds_protocol_graphql_py_lib.dataset.graphql.GraphqlCreateSettings ds_protocol_graphql_py_lib.dataset.graphql.GraphqlDatasetSettings ds_protocol_graphql_py_lib.dataset.graphql.GraphqlDataset Module Contents --------------- .. py:data:: logger .. py:class:: GraphqlReadSettings Bases: :py:obj:`ds_common_serde_py_lib.Serializable` Settings specific to reading data from GraphQL API. .. py:attribute:: query :type: str The GraphQL query string to execute for reading data. This should be a valid GraphQL query that the endpoint can execute to return the desired data. For example: "{ users { id name email } }" .. py:attribute:: variables :type: dict[str, Any] | None :value: None Optional variables to include with the GraphQL query. .. py:attribute:: operation_name :type: str | None :value: None Optional operation name for the GraphQL query, used when the query contains multiple operations. .. py:class:: GraphqlDeleteSettings Bases: :py:obj:`ds_common_serde_py_lib.Serializable` Settings specific to deleting data from GraphQL API. .. py:attribute:: mutation :type: str The GraphQL mutation string to execute for deleting data. .. py:attribute:: identity_columns :type: list[str] The list of column names in the input DataFrame that uniquely identify the rows to delete. .. py:attribute:: variables :type: dict[str, Any] | None :value: None Optional variables to include with the GraphQL mutation. .. py:attribute:: operation_name :type: str | None :value: None Optional operation name for the GraphQL mutation, used when the mutation contains multiple operations. .. py:class:: GraphqlCreateSettings Bases: :py:obj:`ds_common_serde_py_lib.Serializable` Settings specific to creating data in GraphQL API. .. py:attribute:: mutation :type: str The GraphQL mutation string to execute for creating data. This should be a valid GraphQL mutation that the endpoint can execute to create new records based on the input data. For example: "mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name email } }" .. py:attribute:: input_field :type: str The name of the variable in the GraphQL mutation that will receive the input data. .. py:attribute:: operation_name :type: str | None :value: None Optional operation name for the GraphQL mutation, used when the mutation contains multiple operations. .. py:class:: GraphqlDatasetSettings Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.DatasetSettings` The object containing the settings of the dataset. .. py:attribute:: url :type: str The URL of the GraphQL endpoint to connect to. This is the base URL where the GraphQL API is hosted. .. py:attribute:: primary_keys :type: list[str] | None :value: None Optional list of column names that serve as primary keys for the dataset. This can be used for operations that require unique identification of rows. .. py:attribute:: headers :type: dict[str, str] | None :value: None Optional HTTP headers to include in requests to the GraphQL endpoint, such as authentication tokens or content type. .. py:attribute:: read :type: GraphqlReadSettings | None :value: None Settings for read operations. .. py:attribute:: delete :type: GraphqlDeleteSettings | None :value: None Settings for delete operations. .. py:attribute:: create :type: GraphqlCreateSettings | None :value: None Settings for create operations. .. py:data:: GraphqlDatasetSettingsType .. py:class:: GraphqlDataset Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.dataset.TabularDataset`\ [\ :py:obj:`ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType`\ , :py:obj:`GraphqlDatasetSettingsType`\ , :py:obj:`ds_resource_plugin_py_lib.common.serde.serialize.PandasSerializer`\ , :py:obj:`ds_protocol_graphql_py_lib.serde.deserializer.GraphqlDeserializer`\ ], :py:obj:`Generic`\ [\ :py:obj:`ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType`\ , :py:obj:`GraphqlDatasetSettingsType`\ ] Represent Graphql dataset. .. py:attribute:: settings :type: GraphqlDatasetSettingsType .. py:attribute:: linked_service :type: ds_protocol_http_py_lib.dataset.http.HttpLinkedServiceType .. py:attribute:: deserializer :type: ds_protocol_graphql_py_lib.serde.deserializer.GraphqlDeserializer | None .. py:property:: type :type: ds_protocol_graphql_py_lib.enums.ResourceType Get the type of the dataset. .. py:property:: supports_checkpoint :type: bool Indicate whether this provider supports incremental loads via checkpointing. GraphQL provider does not yet support checkpoint-based incremental loads. All reads are full loads. :returns: False, indicating checkpointing is not supported. .. py:method:: read() -> None Read Graphql dataset. Sends a GraphQL query to the endpoint with the query, variables, and operation name specified in settings.read. Populates self.output with the result as a DataFrame. Handles various GraphQL response patterns via GraphqlDeserializer: - Direct arrays: {"data": {"users": [...]}} - Relay connections: {"data": {"users": {"edges": [{"node": {...}}]}}} - Single objects: {"data": {"user": {...}}} :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises ReadError: If read settings are not provided or if the GraphQL query fails. .. py:method:: _check_for_graphql_read_error(response_data: dict[str, Any]) -> None :staticmethod: .. py:method:: create() -> None Create new rows in the GraphQL endpoint using mutations. Sends all rows in a single atomic GraphQL mutation request. Populates self.output with the created rows. :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises CreateError: If create settings are not provided or if the GraphQL mutation fails. .. py:method:: update() -> None Update entity using Graphql. .. py:method:: upsert() -> None Upsert entity using Graphql. .. py:method:: delete() -> None Delete specific rows from the GraphQL endpoint using mutations. Sends all rows in a single atomic GraphQL mutation request. Populates self.output with the deleted rows. :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises DeleteError: If delete settings are not provided, if identity columns are missing, or if the GraphQL mutation fails. .. py:method:: purge() -> NoReturn Purge entity using Graphql. .. py:method:: rename() -> NoReturn Rename entity using Graphql. .. py:method:: list() -> None Discover available resources in the GraphQL schema via introspection. Executes a GraphQL introspection query to fetch all available queries and their arguments from the schema. Populates self.output with a DataFrame containing resource metadata (name, type, description, etc.). :returns: None. The result is stored in self.output as a DataFrame. :raises ConnectionError: If the linked service connection is not initialized. :raises ListError: If the GraphQL introspection query fails. .. py:method:: close() -> None Just to satisfy the contract - GraphQL dataset does not maintain persistent connections that require cleanup. :returns: None .. py:method:: _validate_create_settings() -> None Validate create settings are properly configured. :returns: if settings are valid. :rtype: None :raises CreateError: If any required create settings are missing or invalid.