Client¶

Note

ArchiveClient instances are usually created via YamcsClient.get_archive():

from yamcs.client import YamcsClient

client = YamcsClient('localhost:8090')
archive = client.get_archive(instance='simulator')
# ...

class yamcs.client.ArchiveClient(ctx: Context, instance: str)¶

create_stream_subscription(stream: str, on_data: Callable[[StreamData], None], timeout: float = 60) → WebSocketSubscriptionFuture¶

Create a new stream subscription.

Parameters:

stream – The name of the stream.
on_data – Function that gets called with StreamData updates.
timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription.

dump_table(table: str, query: Optional[str] = None, chunk_size: int = 32768)¶

execute_sql(statement: str) → ResultSet¶

Executes a single SQL statement.

Parameters:: statement – SQL string
Returns:: A result set for consuming rows

export_commands(start: Optional[datetime] = None, stop: Optional[datetime] = None, chunk_size: int = 32768) → Iterable¶

Export command history.

Commands are sorted by generation time, origin and sequence number.

Parameters:

start – Minimum generation time of the returned commands (inclusive)
stop – Maximum generation time of the returned commands (exclusive)

Returns:

An iterator over received chunks

export_packets(name: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, chunk_size: int = 32768) → Iterable¶

Export raw packets.

Packets are sorted by generation time and sequence number.

Parameters:

name – Archived name of the packet
start – Minimum generation time of the returned packets (inclusive)
stop – Maximum generation time of the returned packets (exclusive)

Returns:

An iterator over received chunks

export_parameter_values(parameters: List[str], namespace: Optional[str], start: Optional[datetime] = None, stop: Optional[datetime] = None, interval: Optional[float] = None, chunk_size: int = 32768) → Iterable¶

Export parameter values in CSV format.

New in version 1.9.1.

Parameters:

parameters – List of parameter names. These may be fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
namespace – Preferred namespace of the names in the returned CSV header
start – Minimum generation time of the returned values (inclusive)
stop – Maximum generation time of the returned values (exclusive)
interval – If specified, only one value for each interval is returned. The interval is expressed in seconds.

Returns:

An iterator over received chunks

get_packet(generation_time: datetime, sequence_number: int, partition: Optional[str] = None) → Packet¶

Gets a single packet by its identifying key (partition, gentime, seqNum).

Parameters:

generation_time – When the packet was generated (packet time)
sequence_number – Sequence number of the packet
partition – Packet partition name. This property works only against recent versions of Yamcs,and will become required in the future (it was erroneously omitted).

get_stream(stream: str) → Stream¶

Gets a single stream.

Parameters:: stream – The name of the stream.

get_table(table: str) → Table¶

Gets a single table.

Parameters:: table – The name of the table.

list_alarms(name: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, page_size: int = 500, descending: bool = False) → Iterable[Alarm]¶

Reads alarm information between the specified start and stop time.

Alarms are sorted by trigger time, name and sequence number.

Parameters:

name – Filter by alarm name
start – Minimum trigger time (inclusive)
stop – Maximum trigger time (exclusive)
page_size – Page size of underlying requests. Higher values imply less overhead, but risk hitting the maximum message size limit.
descending – If set to True alarms are fetched in reverse order (most recent first).

list_command_histogram(name: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, merge_time: float = 2) → Iterable[IndexGroup]¶

Reads command-related index records between the specified start and stop time.

Each iteration returns a chunk of chronologically-sorted records.

Parameters:: merge_time – Maximum gap in seconds before two consecutive index records are merged together.

list_command_history(command: Optional[str] = None, queue: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, page_size: int = 500, descending: bool = False) → Iterable[CommandHistory]¶

Reads command history entries between the specified start and stop time.

Note

This method will send out multiple requests when more than page_size commands are queried. For large queries, consider using stream_command_history() instead, it uses server-streaming based on a single request.

Parameters:

command – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
queue – Name of the queue that the command was assigned to.
start – Minimum generation time of the returned command history entries (inclusive)
stop – Maximum generation time of the returned command history entries (exclusive)
page_size – Page size of underlying requests. Higher values imply less overhead, but risk hitting the maximum message size limit.
descending – If set to True results are fetched in reverse order (most recent first).

list_completeness_index(start: Optional[datetime] = None, stop: Optional[datetime] = None, merge_time: float = 2) → Iterable[IndexGroup]¶

Reads completeness index records between the specified start and stop time.

Each iteration returns a chunk of chronologically-sorted records.

Parameters:: merge_time – Maximum gap in seconds before two consecutive index records are merged together.

list_event_histogram(source: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, merge_time: float = 2) → Iterable[IndexGroup]¶

Reads event-related index records between the specified start and stop time.

Each iteration returns a chunk of chronologically-sorted records.

Parameters:: merge_time – Maximum gap in seconds before two consecutive index records are merged together.

list_event_sources() → Iterable[str]¶: Returns the existing event sources.

list_events(source: Optional[str] = None, severity: Optional[str] = None, text_filter: Optional[str] = None, filter: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, page_size: int = 500, descending: bool = False) → Iterable[Event]¶

Reads events between the specified start and stop time.

Events are sorted by generation time, source, then sequence number.

Note

This method will send out multiple requests when more than page_size events are queried. For large queries, consider using stream_events() instead, it uses server-streaming based on a single request.

Parameters:

source – The source of the returned events.
severity – The minimum severity level of the returned events. One of INFO, WATCH, WARNING, DISTRESS, CRITICAL or SEVERE.
text_filter – Filter the text message of the returned events
filter –
Filter query, allows for both text and field search.

New in version 1.10.1: Compatible with Yamcs v5.10.2 onwards
start – Minimum start date of the returned events (inclusive)
stop – Maximum start date of the returned events (exclusive)
page_size – Page size of underlying requests. Higher values imply less overhead, but risk hitting the maximum message size limit.
descending – If set to True events are fetched in reverse order (most recent first).

list_packet_histogram(name: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, merge_time: float = 2) → Iterable[IndexGroup]¶

Reads packet-related index records between the specified start and stop time.

Each iteration returns a chunk of chronologically-sorted records.

Parameters:: merge_time – Maximum gap in seconds before two consecutive index records are merged together.

list_packet_names() → Iterable[str]¶: Returns the existing packet names.

list_packets(name: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, page_size: int = 500, descending: bool = False) → Iterable[Packet]¶

Reads packet information between the specified start and stop time.

Packets are sorted by generation time and sequence number.

Note

This method will send out multiple requests when more than page_size packets are queried. For large queries, consider using stream_packets() instead, it uses server-streaming based on a single request.

Parameters:

name – Archived name of the packet
start – Minimum generation time of the returned packets (inclusive)
stop – Maximum generation time of the returned packets (exclusive)
page_size – Page size of underlying requests. Higher values imply less overhead, but risk hitting the maximum message size limit.
descending – If set to True packets are fetched in reverse order (most recent first).

list_parameter_ranges(parameter: str, start: Optional[datetime] = None, stop: Optional[datetime] = None, min_gap: Optional[float] = None, max_gap: Optional[float] = None, min_range: Optional[float] = None, max_values: int = 100, parameter_cache: str = 'realtime') → List[ParameterRange]¶

Returns parameter ranges between the specified start and stop time.

Each range indicates an interval during which this parameter’s value was uninterrupted and unchanged.

Ranges are a good fit for retrieving the value of a parameter that does not change frequently. For example an on/off indicator or some operational status. Querying ranges will then induce much less overhead than manually processing the output of list_parameter_values() would.

The maximum number of returned ranges is limited to 500.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
start – Minimum generation time of the considered values (inclusive)
stop – Maximum generation time of the considered values (exclusive)
min_gap – Time in seconds. Any gap (detected based on parameter expiration) smaller than this will be ignored. However if the parameter changes value, the ranges will still be split.
max_gap – Time in seconds. If the distance between two subsequent parameter values is bigger than this value (but smaller than the parameter expiration), then an artificial gap is created. This also applies if there is no expiration defined for the parameter.
min_range – Time in seconds. Minimum duration of returned ranges. If multiple values occur within the range, the most frequent can be accessed using the entries property.
max_values – Maximum number of unique values, tallied across the full requested range. Use this in combination with min_range to further optimize for transfer size. This value is limited to 100 at most.
parameter_cache – Specify the name of the processor who’s parameter cache is merged with already archived values. To disable results from the parameter cache, set this to None.

list_parameter_values(parameter: str, start: Optional[datetime] = None, stop: Optional[datetime] = None, page_size: int = 500, descending: bool = False, parameter_cache: str = 'realtime', source: str = 'ParameterArchive') → Iterable[ParameterValue]¶

Reads parameter values between the specified start and stop time.

Note

This method will send out multiple requests when more than page_size values are queried. For large queries, consider using stream_parameter_values() instead, it uses server-streaming based on a single request, and supports downloading the values of multiple parameter at the same time.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
start – Minimum generation time of the returned values (inclusive)
stop – Maximum generation time of the returned values (exclusive)
page_size – Page size of underlying requests. Higher values imply less overhead, but risk hitting the maximum message size limit.
descending – If set to True values are fetched in reverse order (most recent first).
parameter_cache – Specify the name of the processor who’s parameter cache is merged with already archived values. To disable results from the parameter cache, set this to None.
source – Specify how to retrieve parameter values. By default this uses the ParameterArchive which is optimized for retrieval. For Yamcs instances that do not enable the ParameterArchive, you can still get results by specifying replay as the source. Replay requests take longer to return because the data needs to be reprocessed.

list_processed_parameter_group_histogram(group: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, merge_time: float = 20) → Iterable[IndexGroup]¶

Reads index records related to processed parameter groups between the specified start and stop time.

Each iteration returns a chunk of chronologically-sorted records.

Parameters:: merge_time – Maximum gap in seconds before two consecutive index records are merged together.

list_processed_parameter_groups() → Iterable[str]¶: Returns the existing parameter groups.

list_streams() → Iterable[Stream]¶

Returns the existing streams.

Streams are returned in lexicographical order.

list_tables() → Iterable[Table]¶

Returns the existing tables.

Tables are returned in lexicographical order.

load_table(table: str, data, chunk_size: int = 32768) → int¶

purge_parameter_archive()¶

Removes all Parameter Archive data and related metadata.

Afterwards, use rebuild_parameter_archive() to rebuild the Parameter Archive.

rebuild_ccsds_index(start: Optional[datetime] = None, stop: Optional[datetime] = None)¶

Rebuilds the CCSDS index. This is only applicable to projects that use a CcsdsTmIndex service to calculate packet completeness.

Note

Index rebuilds run synchronously: this method will await the outcome.

Parameters:

start – Start time
stop – Stop time

rebuild_histogram(table: str, start: Optional[datetime] = None, stop: Optional[datetime] = None)¶

Rebuilds the histogram for a table. This may be necessary for example after bulk loading data.

The rebuild may be constrained by using the start and stop parameters. When specified all partitions overlapping this range are reconsidered.

Note

Histogram rebuilds run synchronously: this method will await the outcome.

Parameters:

table – The name of the table
start – Start time
stop – Stop time

rebuild_parameter_archive(start: datetime, stop: datetime)¶

Rebuilds the Parameter Archive.

The rebuild must be constrained by using the start and stop parameters. This values are only hints to the Parameter Archive, which will extend the requested range based on archive segmentation.

Note

Rebuilds run as an asynchronous operation: this method will not await the outcome.

Parameters:

start – Start time
stop – Stop time

sample_parameter_values(parameter: str, start: Optional[datetime] = None, stop: Optional[datetime] = None, sample_count: int = 500, parameter_cache: str = 'realtime', source: str = 'ParameterArchive') → List[Sample]¶

Returns parameter samples.

The query range is split in sample intervals of equal length. For each interval a Sample is returned which describes the min, max, count and avg during that interval.

Note that sample times are determined without considering the actual parameter values. Two separate queries with equal start/stop arguments will always return the same number of samples with the same timestamps. This is done to ease merging of multiple sample series. You should always be explicit about the start and stop times when relying on this property.

Parameters:

parameter – Either a fully-qualified XTCE name or an alias in the format NAMESPACE/NAME.
start – Minimum generation time of the sampled parameter values (inclusive). If not set this defaults to one hour ago.
stop – Maximum generation time of the sampled parameter values (exclusive). If not set this defaults to the current time.
sample_count – The number of returned samples.
parameter_cache – Specify the name of the processor who’s parameter cache is merged with already archived values. To disable results from the parameter cache, set this to None.
source – Specify how to retrieve parameter values. By default this uses the ParameterArchive which is optimized for retrieval. For Yamcs instances that do not enable the ParameterArchive, you can still get results by specifying replay as the source. Replay requests take longer to return because the data needs to be reprocessed.

stream_command_history(name: Optional[Union[str, List[str]]] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, chunk_size: int = 32768) → Iterable[CommandHistory]¶

Reads command history between the specified start and stop time.

New in version 1.9.1.

Parameters:

name – If specified, return only commands with this name.
start – Minimum generation time of the returned commands (inclusive)
stop – Maximum generation time of the returned commands (exclusive)

stream_events(source: Optional[Union[str, List[str]]] = None, severity: Optional[str] = None, text_filter: Optional[str] = None, filter: Optional[str] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, chunk_size: int = 32768) → Iterable[Event]¶

Reads events between the specified start and stop time.

New in version 1.9.1.

Parameters:

source – If specified, return only events with this source.
severity – The minimum severity level of the returned events. One of INFO, WATCH, WARNING, DISTRESS, CRITICAL or SEVERE.
text_filter – Filter the text message of the returned events
filter –
Filter query applied to returned events. Allows for both text and field search.

New in version 1.10.1: Compatible with Yamcs v5.10.2 onwards
start – Minimum generation time of the returned events (inclusive)
stop – Maximum generation time of the returned events (exclusive)

stream_packets(name: Optional[Union[str, List[str]]] = None, start: Optional[datetime] = None, stop: Optional[datetime] = None, chunk_size: int = 32768) → Iterable[Packet]¶

Reads packet information between the specified start and stop time.

New in version 1.9.1.

Parameters:

name – If specified, return only packets with this archived name.
start – Minimum generation time of the returned packets (inclusive)
stop – Maximum generation time of the returned packets (exclusive)

stream_parameter_values(parameters: Union[str, List[str]], start: Optional[datetime] = None, stop: Optional[datetime] = None, tm_links: Optional[Union[str, List[str]]] = None, chunk_size: int = 32768) → Iterable[ParameterData]¶

Reads parameter values between the specified start and stop time.

Value updates are emitted for each unique generation time within the queried range. If one of the parameters does not have a value for a specific generation time, it is not included in the update.

Parameters:

parameters – Parameter(s) to be queried.
start – Minimum generation time of the returned values (inclusive)
stop – Maximum generation time of the returned values (exclusive)
tm_links –
If set, include only values that were received through a specific link.

New in version 1.8.4: Compatible with Yamcs 5.7.4 onwards